Domains & DKIM

Before you can send from an address, you must verify the domain it lives on. Verification proves ownership and configures the authentication that mailbox providers check on every message — SPF, DKIM, and DMARC alignment.

1. Register the domain

Call POST /v1/domains with the bare domain. MailStack provisions an identity with the sending provider (SES Easy DKIM) and returns a Pending domain with the exact DNS records you need to publish:

curl https://api.mailstack.voostack.com/v1/domains \
  -H "Authorization: Bearer ms_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.com" }'

The response includes a dnsRecords array:

{
  "id": "3b1f…",
  "domain": "yourdomain.com",
  "status": "Pending",
  "customMailFromDomain": "mail.yourdomain.com",
  "dnsRecords": [
    { "type": "CNAME", "name": "abc123._domainkey.yourdomain.com",
      "value": "abc123.dkim.amazonses.com", "ttl": 1800, "purpose": "DKIM" },
    { "type": "MX", "name": "mail.yourdomain.com",
      "value": "10 feedback-smtp.us-east-1.amazonses.com", "ttl": 1800, "purpose": "MAIL FROM" },
    { "type": "TXT", "name": "mail.yourdomain.com",
      "value": "v=spf1 include:amazonses.com ~all", "ttl": 1800, "purpose": "SPF" }
  ],
  "createdAt": "2026-06-18T10:00:00Z"
}

2. Publish the DNS records

Add each record exactly as returned at your DNS provider. DKIM uses CNAME records that delegate signing to the provider, the MAIL FROM subdomain gets an MX and SPF record for alignment, and we recommend adding a DMARC policy record too:

_dmarc.yourdomain.com  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"

Start DMARC at p=none to collect reports, then tighten to quarantine or reject once you've confirmed alignment.

3. Verify

DNS can take anywhere from a few minutes to a few hours to propagate. Trigger a re-check with POST /v1/domains/{id}/verify. When all records resolve, the domain flips to Verified and you can send from any address on it.

curl -X POST https://api.mailstack.voostack.com/v1/domains/3b1f…/verify \
  -H "Authorization: Bearer ms_live_xxxxxxxxxxxx"

Why alignment matters

Passing SPF or DKIM isn't enough on its own — DMARC requires the authenticated domain to align with the visible From address. MailStack's custom MAIL FROM subdomain and Easy DKIM ensure both align by default, which is the single biggest lever for inbox placement. For a deeper dive, read how email deliverability actually works.

Managing domains

• GET /v1/domains — list all domains for your org.
• GET /v1/domains/{id} — fetch one domain with its records and status.
• DELETE /v1/domains/{id} — remove a domain.