Skip to content
DashboardGet API key

Add an email domain

View .md
POST

Add a domain to send email from. domain is validated first: a bare domain (a leading https:// and a trailing path are dropped); anything else, spaces included, is 400 with details.errors[0].path ["domain"]. Adding a domain the project already has returns it with 200 (nothing created), like POST /v2/channels.

Returns the DNS records to publish; the DKIM CNAMEs are required. If they could not be generated, the domain is still created (201) but comes back verifiable: false with setupError: remove it and add it again, or contact support. Verify cannot fix it.

Publish the records exactly as returned, verify, then connect an address with POST /v2/channels {"type":"email"}.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • domainstringrequired

Responses

200Already a domain of this project; returned as it is, nothing created.
  • domainobjectrequired
    7 properties
    • idstringrequired
    • domainstringrequired
    • statusstringrequired

      Overall verification status.

    • dkimStatusstringrequired
    • dnsRecordsobject[]

      DNS records to publish. Present when fetching a single domain or after adding one.

      6 properties
      • typestringrequired

        DNS record type.

      • namestringrequired

        Record host/name to create.

      • valuestringrequired

        Record value.

      • priorityinteger

        Priority (MX records only).

      • purposestringrequired

        What the record is for.

        One ofdkimspfdmarcmail_from
      • requiredbooleanrequired

        Whether the record is required to verify + send (DKIM) or recommended for deliverability.

    • verifiableboolean

      Present with dnsRecords. False when the DKIM records could not be generated: such a domain cannot verify whatever DNS you publish, and setupError says what to do.

    • setupErrorobject

      Present when verifiable is false. recommendation is the same everywhere this domain is refused (POST .../verify, POST /v2/channels): remove the domain and add it again, which sets it up from scratch; contact support if the new one has no dkim record either. It never says to retry verify or to publish the other records.

      3 properties
      • codestring
        One ofdkim_records_unavailable
      • messagestring
      • recommendationstring
201Domain added.
  • domainobjectrequired
    7 properties
    • idstringrequired
    • domainstringrequired
    • statusstringrequired

      Overall verification status.

    • dkimStatusstringrequired
    • dnsRecordsobject[]

      DNS records to publish. Present when fetching a single domain or after adding one.

      6 properties
      • typestringrequired

        DNS record type.

      • namestringrequired

        Record host/name to create.

      • valuestringrequired

        Record value.

      • priorityinteger

        Priority (MX records only).

      • purposestringrequired

        What the record is for.

        One ofdkimspfdmarcmail_from
      • requiredbooleanrequired

        Whether the record is required to verify + send (DKIM) or recommended for deliverability.

    • verifiableboolean

      Present with dnsRecords. False when the DKIM records could not be generated: such a domain cannot verify whatever DNS you publish, and setupError says what to do.

    • setupErrorobject

      Present when verifiable is false. recommendation is the same everywhere this domain is refused (POST .../verify, POST /v2/channels): remove the domain and add it again, which sets it up from scratch; contact support if the new one has no dkim record either. It never says to retry verify or to publish the other records.

      3 properties
      • codestring
        One ofdkim_records_unavailable
      • messagestring
      • recommendationstring
400Missing or invalid `domain` (`details.errors`, `path: ["domain"]`), or the domain could not be set up (the message says what to do).
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring