Domains

You may only send from a domain you have proved you control. Adding one returns every record you need to publish.

Add a domain

POST/v1/domains

request · json

{ "name": "yourdomain.com" }

A domain can belong to exactly one organization. If another account has already claimed it, the request is refused — otherwise two tenants could send as each other.

Records

Purpose	Type	Required	What it does
`dkim` (×3)	CNAME	Yes	Cryptographically signs your mail
`mail_from_mx`	MX	Yes	Routes bounces to a subdomain you own
`mail_from_spf`	TXT	Yes	Authorises the sending infrastructure
`dmarc`	TXT	No	Tells receivers what to do with failures

Do not skip the MAIL FROM records

DKIM alone is not enough. Without a custom MAIL FROM your Return-Path sits on a shared bounce domain, SPF authenticates that domain rather than yours, and DMARC alignment fails even though DKIM passes. Verification will not complete until both records resolve.

Check verification

GET/v1/domains/{name}/records

Every record is resolved live over DNS and returned with a published flag. This is the endpoint to build your setup UI against: almost every failed onboarding is one mistyped record, and an aggregate “pending” gives the customer nothing to act on.

json

{
  "domain": "yourdomain.com",
  "verificationState": "pending",
  "records": [
    {
      "type": "CNAME",
      "name": "abc123._domainkey.yourdomain.com",
      "value": "abc123.dkim.example.net",
      "purpose": "dkim",
      "required": true,
      "published": true
    }
  ]
}

States

State	Meaning
`pending`	Records not yet all visible. Polled every minute.
`verified`	DKIM and MAIL FROM both confirmed. You can send.
`temporary_failure`	A record disappeared. Restore it and it recovers.
`failed`	Rejected, or unverified after 72 hours. Delete and re-add.

DNS propagation is usually minutes but can take a day. Verification becomes effective within about a minute of the records appearing.

List and remove

GET/v1/domains

DELETE/v1/domains/{id}

Deleting a domain stops you sending from it immediately. Messages already queued are not recalled.