Domains & DNS setup

Before you can send from an address, the sending domain has to be verified. Verification proves you control the domain and lets Anypost authenticate your mail.

How verification works

Mailbox providers only trust authenticated mail, and authentication relies on DNS: SPF, DKIM, and MX records. Configuring them by hand is error-prone, and the values change over time.

Anypost manages those records for you. When you add a domain, Anypost generates its DKIM keys and publishes the authoritative SPF, DKIM, and MX records in its own DNS. You publish a small set of CNAME records pointing your domain at Anypost's. Your DNS holds only CNAMEs; Anypost holds the records that actually change. Once the CNAMEs are published, Anypost can rotate DKIM keys behind them without you touching DNS again.

Add a domain

Add a domain in the dashboard, or with POST /v1/domains:

curl https://api.anypost.com/v1/domains \
  -H "Authorization: Bearer $ANYPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "example.com" }'

Add the exact domain you will put in from addresses. To send from mail.example.com, add it as its own domain.

The response includes the domain's id, a status of pending, and a dns_records array: the records to publish next.

Publish the DNS records

dns_records lists every record to create at your DNS provider. Each one is a CNAME:

Field	What it is
`type`	Always `CNAME`.
`name`	The record name, relative to your domain's registered apex.
`value`	The target the CNAME points to.
`purpose`	`verification` or `dkim`.

A typical domain has three records: one verification and two dkim. Publish each one exactly as given.

The name is relative to the registered apex, the form most provider UIs expect. For example.com the verification record is named anypost. For a subdomain like mail.example.com it is anypost.mail.

DNS changes are not instant. Providers and resolvers cache records, so a new CNAME can take anywhere from a few minutes to a few hours to become visible.

Verify the domain

Once the records are published, verify the domain in the dashboard, or call:

curl -X POST https://api.anypost.com/v1/domains/domain_550e8400.../verify \
  -H "Authorization: Bearer $ANYPOST_API_KEY"

Anypost resolves your CNAMEs and checks that they reach its records. The response returns the domain with an updated status:

verified: the domain is ready. You can send from it.
pending: not all records were found yet. verification_failure says why.

If you published the records moments ago, verification can fail simply because DNS has not propagated. Wait, then verify again. The call is safe to repeat as often as you like.

When verification fails

verification_failure.code identifies the problem. Its message restates the same thing with your domain's actual record names filled in.

Code	Meaning
`apex_cname_missing`	The verification CNAME was not found. Check the record name and that it is published.
`apex_cname_mismatch`	The verification CNAME exists but points to the wrong target.
`dkim_cname_missing`	A DKIM CNAME was not found.
`dkim_cname_mismatch`	A DKIM CNAME points to the wrong target.
`dkim_mismatch`	A DKIM record resolves but its key does not match. Re-check the CNAME target.
`chain_broken`	A published CNAME resolves, but the chain through to Anypost's records is broken.
`mx_missing`	The MX record is not resolving through. Usually a propagation delay.
`spf_missing`	The SPF record is not resolving through. Usually a propagation delay.

Most failures right after publishing are propagation delays. Confirm the record name and value match what dns_records gave you, then verify again.

Branded tracking (optional)

Open and click tracking can run under a branded subdomain of your domain, such as track.example.com. It uses one additional CNAME and is verified separately. Tracking is independent of mail flow: a tracking-CNAME problem never blocks sending. See Tracking domains.

Where to go next

Send a single email: now that a domain is verified, send from it.
Sending over SMTP: send through the SMTP transport instead.
Tracking domains: add branded open and click tracking.