Docs

Use your own domain

Sending agent mail from a domain you control means publishing DNS records yourself. This application never writes, edits or removes a record on your behalf — it tells you the exact values and then checks what is actually published.

Last reviewed September 21, 2026 against the implementation in this repository.

A platform address on agents.emailforagents.ai works with no DNS at all and is the right place to start; this page is for when an agent inbox needs to be at your own domain instead. If you have not created any inbox yet, do the quickstart first.

What you need first

• A live project. Test projects cannot attach domains at all; the attempt returns test_mode_unsupported, and test addresses stay on non-routable .mail.invalid hosts.
• An eligible paid subscription. Attaching a domain without one returns payment_required. Each plan has a custom-domain count; exceeding it returns quota_exceeded.
• Access to your DNS zone, and a change window if the domain already carries mail.

Start with a dedicated subdomain

Use a hostname such as agents.example.com rather than your company's root domain. Three reasons, in order of how much they will cost you if you ignore them:

1. Receiving mail at a hostname means publishing MX there. Publish MX at a hostname that already receives employee mail and you redirect that mail. A subdomain has no existing MX to break.
2. Sending reputation stays separated. An agent that gets a bounce or a complaint does not drag your primary domain's reputation with it.
3. Revocation is a zone edit. Removing a subdomain's records is a contained change you can make in a minute.

Preview the exact hostname in Domains before attaching it. The preview resolves DNS to see whether MX already exists; it does not attach a provider domain and it changes nothing. If MX is found, keep the default preserve_existing mode: that enables sending verification for the hostname and leaves receiving disabled, so nothing you publish can interrupt delivery to existing mailboxes. The preview will also suggest agents.<your domain> as the safer target.

Choose migrate only when you genuinely intend to move all receiving mail at that hostname. It records your consent; it still makes no DNS changes.

The records, and the order they appear in

You do not get every record up front, and that is deliberate: the provider-issued sending and receiving values are only created after ownership is proven. Asking you to publish them earlier would mean handing out mail-routing records for a hostname nobody had demonstrated control of.

Type   TXT
Host   _efa-challenge.agents.example.com     (relative: _efa-challenge)
Value  efa-ownership=efa_9c41a7...

The console shows both the fully-qualified host and the relative host, because DNS providers disagree about which one they want — some expect _efa-challenge.agents.example.com, others expect _efa-challenge with the zone appended for you. Publishing both forms creates a record at _efa-challenge.agents.example.com.agents.example.com, which is the single most common reason verification does not complete.

Each record carries its own status while you work:

Verifying ownership

1. Attach the domain. Copy its unique _efa-challenge TXT record into your DNS provider.
2. Leave the TXT record in place — permanently — and choose Check verification and provider setup.
3. Once ownership is confirmed, the console displays the exact SPF, DKIM and receiving records returned by the mail provider, including MX priority.
4. Publish those records at their displayed hosts.
5. Check again after DNS propagates. Each check reads DNS live; it never writes.

Only one verification check runs at a time per domain — a second concurrent request returns temporarily_unavailable rather than racing the first. An explicit check can also ask the provider to re-run its own verification, at most once a minute. Between your checks, the system re-reads DNS in the background roughly every five minutes, so a record you remove later will be noticed.

Three statuses, not one

Ownership, sending and receiving are tracked separately because they can genuinely disagree: a domain can be authenticated for sending while receiving nothing.

Receiving readiness requires the MX set at the hostname to match the provider's set exactly — same hosts, same values, same priorities, and no extras. An additional MX at any priority is a real routing path to somewhere else, so readiness stays pending until it is removed. This is the check that most often surprises people who left an old record behind.

Creating an address

Attaching a domain does not create an inbox. When the statuses you need are ready, go back to Inboxes, select the same live project, choose the custom hostname under Address domain, and give the inbox a display name and optional local part.

Then prove both directions before you hand it to an agent: send a message to the new address from a mailbox you control, and have the inbox reply. A ready status is evidence that the configuration is correct. It is not a promise about whether a particular recipient's provider will place your mail in their inbox, and nothing on this page can be.

Using the API

POST /v1/projects/{project_id}/domains
{
  "domain": "agents.example.com",
  "receiving_mode": "preserve_existing"
}

receiving_mode defaults to preserve_existing. Supply "receiving_mode": "migrate" to record an intentional migration of all mail at that hostname; it changes what the wizard will offer, not your DNS.