Custom Domains — Domain Verification API for Sending

Out of the box, every agent sends from the shared send.mails.ai domain — working email in one API call. When you want recipients to see your brand, add your own domain through the domain verification API and every agent on it sends as agent@yourcompany.com, DKIM-signed and fully authenticated. Custom domains are available on paid plans (Pro and Scale).

Domain verification API endpoints

Five endpoints cover the full lifecycle:

• POST /v1/domains — Register a custom sending domain. Returns the DNS records to create at your registrar. (scope: manage)
• GET /v1/domains — List all custom domains in the workspace. (scope: read)
• GET /v1/domains/{id} — Get a single domain with its current per-record verification status. (scope: read)
• POST /v1/domains/{id}/verify — Trigger an immediate DNS check and update per-record and overall status. (scope: manage)
• DELETE /v1/domains/{id} — Remove a domain. Agents on it stop sending until the domain is re-added and verified. (scope: manage)

Full request and response shapes are in the API reference.

Add and verify a domain

1. 1

   Register the domain

   POST /v1/domains registers your domain and returns the DNS records to create. No nameserver change is needed — only individual records.

   cURL

   curl https://api.mails.ai/v1/domains \
     -H "Authorization: Bearer $MAILS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "domain": "mail.acme.com" }'

   The response includes each DNS record with its type, host, value, and purpose:

   JSON

   {
     "id": "dom_01JZXE8S0U2W4Y6A8C0E2G4J6L",
     "domain": "mail.acme.com",
     "status": "pending",
     "dns_records": [
       {
         "type": "TXT",
         "host": "dkim._domainkey.mail.acme.com",
         "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq…",
         "purpose": "dkim",
         "required": true,
         "verified": false,
         "instruction": "Add this record exactly as shown. This is what signs your mail."
       },
       {
         "type": "TXT",
         "host": "mail.acme.com",
         "value": "v=spf1 ip4:15.204.67.226 ~all",
         "purpose": "spf",
         "required": false,
         "verified": false,
         "instruction": "If you already publish an SPF record, add ip4:15.204.67.226 to it."
       },
       {
         "type": "TXT",
         "host": "_dmarc.mail.acme.com",
         "value": "v=DMARC1; p=none; …",
         "purpose": "dmarc",
         "required": false,
         "verified": false,
         "instruction": "Publish only if you have no DMARC record today."
       }
     ]
   }

2. 2

   Create the DNS records at your registrar

   Copy each record into your DNS host exactly as the API returns it. The instruction field on each record tells you what to do — in particular, for SPF it says to merge into an existing record rather than replace it. Only the records marked "required": true gate verification; optional records (SPF, DMARC, tracking) improve deliverability and reporting.

3. 3

   Verify the domain

   mails.ai re-checks an unverified domain automatically every 15 minutes, so most domains verify on their own within the hour. To check immediately after adding records, call POST /v1/domains/{id}/verify:

   cURL

   curl -X POST https://api.mails.ai/v1/domains/dom_01JZXE8S0U2W4Y6A8C0E2G4J6L/verify \
     -H "Authorization: Bearer $MAILS_API_KEY"

   The response is the full domain object with refreshed per-record verification state. When every required record is found, status moves to "verified" and agents on the domain start sending under your brand.

Domain status lifecycle

A domain moves through these states:

• pending — records issued, none verified yet.
• verifying — a check is in progress right now.
• verified — every required record was found. Agents on this domain send under their own identity.
• failed — 20 consecutive verify calls did not pass. Not final: the domain is still re-checked automatically (at least once a day), and it verifies the moment its records resolve. The failure count resets on success or after a day without a verify call.

Check verification status

GET /v1/domains/{id} returns the domain with each record's verified flag and the overall status:

curl https://api.mails.ai/v1/domains/dom_01JZXE8S0U2W4Y6A8C0E2G4J6L \
  -H "Authorization: Bearer $MAILS_API_KEY"

When a record is not yet found, its verified is false and the domain's fail_reason says what is missing. When status is "verified", the domain is ready.

List all domains

curl https://api.mails.ai/v1/domains \
  -H "Authorization: Bearer $MAILS_API_KEY"

Remove a domain

DELETE /v1/domains/{id} removes the domain. Agents with addresses on it stop sending immediately — every send from them is refused with 422 domain_not_verified until the domain is added and verified again, or the agents are moved to another domain.

curl -X DELETE https://api.mails.ai/v1/domains/dom_01JZXE8S0U2W4Y6A8C0E2G4J6L \
  -H "Authorization: Bearer $MAILS_API_KEY"

DNS records explained

Each record the API returns includes a purpose that tells you what it does:

• dkim — the DKIM signing key. Required. This is what proves to receiving servers that the email was sent by you.
• spf — your domain's SPF record. Optional. If you already have one, merge the IP into it rather than replacing it.
• dmarc — your domain's DMARC policy. Optional. Publish only if you have no DMARC record today.
• return_path — the bounce address. Points bounces back through mails.ai so they are handled automatically.
• tracking — link tracking. Lets open and click tracking use your domain instead of a platform URL.
• ownership — proof you control the domain, when the sending provider requires it.

Automated verification

You rarely need to poll. mails.ai checks an unverified domain every 15 minutes and a failed one at least once a day, regardless of the workspace's plan or the domain's age. The domain verifies at the first check after its DNS records resolve — no API call needed. Use POST /v1/domains/{id}/verify only when you want an immediate answer after creating the records, or to confirm a fix to a failing record.

Agents on a custom domain

Once a domain is verified, agents whose address is on it send under their own identity instead of the shared send.mails.ai subdomain. The agent's address in the API is support@acme.mails.ai and its mail goes out as support@mail.acme.com — DKIM-signed with the key the domain verification API generated. Until the domain verifies, those same agents send from the built-in send.mails.ai domain as usual.

For the marketing side of custom domains — branding, authentication, and pricing — see the custom domain email for AI agents guide.

Common questions