Set up a sending domain

Verify a sending domain before using it in a from address. Register a domain you control, publish the DNS records Mail returns, and wait for verification. You can then send from any address at that domain.

Sending domains belong to one product and are not visible from another.

Before you start: have a product with Mail available, a domain it owns and access to the domain’s DNS. The examples use mail.example.com under example.com; replace both names and the example domain ID with your own. For setup through the first delivery, use send your first email.

Choose what to register

Choose an apex your product already owns or a subdomain of it. Any other name returns 422 domain_not_governed.

Register the domain

1. Find an allowed apex. Call mail_domain_allowed_list, or GET /mail/domains/allowed on the Mail API. In Mail → Domains → Add domain, the Domain selector uses the same list and shows when it is empty.

   [
     {
       "domainId": "d3f1…",
       "domain": "example.com",
       "mode": "external",
       "extensionCount": 2
     }
   ]

2. Create the sending domain. Call mail_domain_create, or POST /mail/domains, with the required name. The optional region defaults to eu-north-1 and fixes the sending identity’s location. You cannot change it later; moving regions requires deletion and registration again.

   { "name": "mail.example.com", "region": "eu-north-1" }

   Save the returned id and DNS records. A new domain has status: "pending":

   {
     "id": "8e2c…",
     "name": "mail.example.com",
     "region": "eu-north-1",
     "status": "pending",
     "records": [
       {
         "type": "CNAME",
         "name": "abc123._domainkey.mail.example.com",
         "value": "<the signing host Mail returns>",
         "purpose": "dkim",
         "required": true
       },
       {
         "type": "TXT",
         "name": "_dmarc.mail.example.com",
         "value": "v=DMARC1; p=none;",
         "purpose": "dmarc",
         "required": false
       }
     ],
     "verificationStartedAt": "2026-08-02T09:00:00.000Z",
     "verifiedAt": null,
     "active": false
   }

3. Publish the DNS records. Copy every returned record to your DNS provider without changing its name or value. Keep the domain’s id for the next step. Mail → Domains → <domain> lists each record’s type, name, value, priority and DNS resolution state, with a copy button for its value.

4. Check verification. Call mail_domain_verify, use POST /mail/domains/:id/verify, or select Verify now on the domain page. Read resolved in the immediate-check response to see which records Mail could resolve. This per-record flag appears only in that response: domain reads, lists, creation and updates omit it, even after verification. The page refreshes automatically in pending or temporary_failure.

   Check the result: status must be verified and active must be true. A send before verification returns 422 invalid_from_address.

Registration returns 409 if the name is already registered in that region by any product. A host already claimed elsewhere in your product returns 409 host_taken, naming its holder. A failed create is rolled back, so you can retry the name after resolving the conflict.

The DNS records

For each record, copy type, name and value. purpose explains its role, and required tells you whether verification depends on it. Include priority when the record is MX.

Statuses

active: true means both verification and the domain’s host claim are active. Check this field to confirm the domain can send now.

A send using an unverified domain returns 422 invalid_from_address. A domain not registered in this product returns 404.

When verification does not complete

Mail starts verification at creation and checks unsettled domains every minute. DNS propagation usually takes minutes but can take hours with a long TTL. Checks continue for 72 hours from verificationStartedAt; a domain still unverified at that point becomes failed.

After failed, automatic checks do not resume. Fix the DNS records, delete the domain and register it again to start a new 72-hour window.

Change how the domain sends

To change tracking or TLS, call mail_domain_update or PATCH /mail/domains/:id. Send only fields you want to change. The workspace displays TLS on the domain page but has no controls for changing TLS or tracking. Neither name nor region can be patched.

Open and click tracking start disabled. Confirmations, receipts and account recovery messages usually leave them disabled.

Read all domains with mail_domain_list or GET /mail/domains; read one with mail_domain_get or GET /mail/domains/:id. An ID from another product returns 404. Mail → Domains lists name, status, region and creation date. Its detail page adds TLS, the last-check time and DNS records.

Remove a domain

1. Delete the domain. Call mail_domain_delete or DELETE /mail/domains/:id. In the workspace, select Delete on the domain page and confirm the named domain. The screen returns to Mail → Domains.

2. Check the result. The response is { "deleted": true }. Sending from this domain stops immediately and its host claim is released, allowing registration in this or another product. Previously sent messages retain their history.

Next steps

• Authenticate the public API: Authorize application sends with a public key.
• Send a message: Create a message and inspect the response.
• Handle bounces and protect your sending: Check how bounces affect sending.
• Send your first email: Follow setup through your first delivery.