Custom Domains

By default, mailboxes use the mails0.com domain. Custom domains let your agents send and receive email from your own domain (e.g., [email protected]).

Overview

Setting up a custom domain involves three steps:

Register the domain via POST /v1/domains
Add DNS records at your DNS provider (MX, SPF, DMARC)
Verify the domain via POST /v1/domains/:id/verify

Register a Domain

POST/v1/domains — Register a custom domain

curl -s -X POST -H "Authorization: Bearer $MAILS_API_KEY" \
  -H "Content-Type: application/json" \
  "https://mails-worker.genedai.workers.dev/v1/domains" \
  -d '{"domain": "yourcompany.com"}'

Response includes the DNS records you need to add (as an object with mx, spf, and dmarc keys):

{
  "id": "dom_abc123",
  "domain": "yourcompany.com",
  "status": "pending",
  "dns_records": {
    "mx": {
      "type": "MX",
      "host": "yourcompany.com",
      "value": "isaac.mx.cloudflare.net",
      "priority": 10,
      "purpose": "Route inbound email to Cloudflare Email Routing"
    },
    "spf": {
      "type": "TXT",
      "host": "yourcompany.com",
      "value": "v=spf1 include:amazonses.com include:_spf.mx.cloudflare.net ~all",
      "purpose": "Authorize Resend (via SES) and Cloudflare to send on your behalf"
    },
    "dmarc": {
      "type": "TXT",
      "host": "_dmarc.yourcompany.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:[email protected]",
      "purpose": "DMARC policy for authentication failure handling (recommended)"
    }
  },
  "instructions": "Add these DNS records to yourcompany.com, then POST /v1/domains/dom_abc123/verify to check."
}

Required DNS Records

MX Records (Inbound Email)

MX records route inbound email through Cloudflare Email Routing, which forwards messages to your mails-agent Worker.

Type	Name	Value	Priority
MX	`yourcompany.com`	`isaac.mx.cloudflare.net`	10

SPF Record (Outbound Email)

The SPF TXT record authorizes your sending providers (Resend and/or Amazon SES) to send email on behalf of your domain. Without it, outbound email is likely to be marked as spam.

Type	Name	Value
TXT	`yourcompany.com`	`v=spf1 include:amazonses.com include:_spf.mx.cloudflare.net ~all`

If you use Resend instead of SES, replace include:amazonses.com with include:_spf.resend.com.

DMARC Record (Recommended)

DMARC is not strictly required but strongly recommended. It improves deliverability and lets you monitor authentication failures.

Type	Name	Value
TXT	`_dmarc.yourcompany.com`	`v=DMARC1; p=quarantine; rua=mailto:[email protected]`

The default policy is p=quarantine, which instructs receiving servers to quarantine messages that fail authentication checks. Reports are sent to [email protected].

Verify a Domain

After adding DNS records, trigger verification. The API checks your DNS records via Cloudflare DNS over HTTPS (DoH) at https://cloudflare-dns.com/dns-query.

POST/v1/domains/:id/verify — Check DNS and verify domain

curl -s -X POST -H "Authorization: Bearer $MAILS_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/domains/dom_abc123/verify"

Response on success:

{
  "id": "dom_abc123",
  "domain": "yourcompany.com",
  "status": "dns_verified",
  "mx_verified": true,
  "spf_verified": true,
  "message": "Domain verified! You can now create mailboxes on this domain."
}

Response when DNS is not yet propagated:

{
  "id": "dom_abc123",
  "domain": "yourcompany.com",
  "status": "pending",
  "mx_verified": false,
  "spf_verified": false,
  "message": "Verification incomplete. MX: MISSING, SPF: MISSING"
}

Domain Status

Domains progress through two states:

Status	Meaning
`pending`	Domain registered but DNS records have not been verified yet.
`dns_verified`	Required DNS records are confirmed. Domain is fully operational for sending and receiving.

Managing Domains

GET/v1/domains — List all domains

curl -s -H "Authorization: Bearer $MAILS_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/domains"

{
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "yourcompany.com",
      "status": "dns_verified",
      "mx_verified": true,
      "spf_verified": true,
      "dkim_verified": false,
      "created_at": "2026-04-01T12:00:00Z",
      "verified_at": "2026-04-01T12:15:00Z"
    }
  ]
}

DELETE/v1/domains/:id — Remove a custom domain

curl -s -X DELETE -H "Authorization: Bearer $MAILS_API_KEY" \
  "https://mails-worker.genedai.workers.dev/v1/domains/dom_abc123"

DNS Propagation

DNS changes can take anywhere from a few minutes to 48 hours to propagate, depending on your DNS provider and TTL settings. If verification fails, wait a few minutes and try again.

You can check DNS propagation yourself using Cloudflare DoH:

# Check MX records
curl -s "https://cloudflare-dns.com/dns-query?name=yourcompany.com&type=MX" \
  -H "Accept: application/dns-json" | jq

# Check SPF record
curl -s "https://cloudflare-dns.com/dns-query?name=yourcompany.com&type=TXT" \
  -H "Accept: application/dns-json" | jq

# Check DMARC record
curl -s "https://cloudflare-dns.com/dns-query?name=_dmarc.yourcompany.com&type=TXT" \
  -H "Accept: application/dns-json" | jq