# Custom domain email for AI agents: DNS setup guide

> Put AI agent inboxes on your own domain: what the MX, SPF, DKIM and DMARC records do, subdomain or main domain, and how to check that the setup worked.

Source: https://trotta.email/learn/custom-domain-email-for-agents

To put agent inboxes on your own domain, publish DNS records that route the domain's mail to your inbox provider (MX) and let receivers verify what it sends (SPF, DKIM and DMARC). Use a subdomain such as agents.trotta.io so the main domain's mail stays where it is, then verify the records before creating inboxes.

Updated November 20, 2026

## Why put agent inboxes on your own domain?

An address on your own domain tells a recipient who the agent works for. `riley@agents.trotta.io` reads as Trotta's agent. An address on a shared domain reads as someone else's service.

You also own the name. The addresses, and the sending reputation they build, stay with your domain if you ever change provider. A shared domain is still the quickest start, and for sign-up codes and tests it is often enough.

## Which DNS records are involved?

Four kinds of DNS record are involved: MX, SPF, DKIM and DMARC. Most providers add a fifth that proves the domain is yours. MX routes incoming mail. The other three let receiving servers check that outgoing mail really came from your domain.

| Record | Type | Where it lives | What it does |
| --- | --- | --- | --- |
| MX | MX | The mail domain itself | Names the servers that accept mail for the domain. Without it, nothing arrives. |
| SPF | TXT | The mail domain itself | Lists who may send for the domain. A name holds one SPF record. |
| DKIM | TXT | A selector under `_domainkey` | Publishes the public key that outgoing mail is signed against. |
| DMARC | TXT | `_dmarc` under the domain | Tells receivers what to do with mail that fails SPF and DKIM, and where to send reports. |
| Ownership | TXT | A name the provider gives you | Proves you control the domain before any mail is routed. |

In a zone file the general shapes look like this. The provider names are placeholders. Always copy the real values from your provider.

General shapes, not real values:

```text
agents.example.com.                      MX   10 mx.provider.example.
agents.example.com.                      TXT  "v=spf1 include:spf.provider.example ~all"
selector._domainkey.agents.example.com.  TXT  "v=DKIM1; p=<public key>"
_dmarc.agents.example.com.               TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"
```

DMARC passes when SPF or DKIM passes for a domain that matches the visible From address. [SPF, DKIM and DMARC](https://trotta.email/learn/spf-dkim-dmarc) explains each check.

## Subdomain or main domain?

Put agent inboxes on a subdomain, unless you mean to move all of the domain's mail. MX records apply to one exact name. Mail for `trotta.io` follows the MX records at `trotta.io`, and mail for `agents.trotta.io` follows the MX records at `agents.trotta.io`. So a subdomain can route to an agent inbox provider while the main domain keeps its Google Workspace or Microsoft 365 mailboxes.

|  | Subdomain | Main domain |
| --- | --- | --- |
| Address | `riley@agents.trotta.io` | `riley@trotta.io` |
| Existing mailboxes | Untouched | All mail for the domain moves to the new provider |
| SPF | A new record on the subdomain | Merged into the record already there |
| DMARC | Its own record, or the main domain's policy applies | The policy already there stays in charge |
| Reputation | Kept apart from the main domain's mail | Shared with everything the domain sends |
| Fits | Agents beside an existing mail setup | A new domain, or humans and agents moving together |

Two details catch teams out. A name holds one SPF record, so on a name that already has one, the new include is merged into it and never added as a second record. And a subdomain with no DMARC record of its own falls under the main domain's policy.

## How do you connect a domain to Trotta Mail?

Connecting a domain to Trotta Mail takes three steps: add the domain, publish its five records, verify. Mail for the domain is then screened before it is delivered, the same as mail for `trotta.email`.

Your own domain is on paid plans only: up to 3 domains on Developer and up to 25 on Startup. On Free, adding one answers `403 domain_limit_reached`.

Add the domain. The key needs the `admin` scope.

```bash
curl -X POST https://api.trotta.email/v1/domains \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents.trotta.io"}'
```

The answer lists five records. Each has a `purpose` (`ownership`, `inbound`, `spf`, `dkim` or `dmarc`), a `type`, a `value`, and its name in two forms: `name` in full, and `host`, the part before the zone. Most DNS providers ask for the host. Print them as a table:

```bash
curl -s https://api.trotta.email/v1/domains/dom_2Yq5hLf6 \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  | jq -r '.records[] | [.purpose, .type, .host, (.priority // "-"), .value] | @tsv'
```

Then publish them at your DNS provider, in one of three ways.

- **By hand.** Copy each record. This works at every DNS provider.
- **Zone file.** `GET /v1/domains/{id}/zone-file` returns the same records as a BIND zone file to import.
- **One click.** `POST /v1/domains/{id}/connect` returns a link to approve the records at your DNS provider, where the provider supports Domain Connect and has switched Trotta Mail on. Trotta Mail never sees your password there.

The one-click path guards the two details above. It merges the SPF include into a record that is already there, and it never replaces a DMARC policy. If mail for the name goes elsewhere today, it answers `409 mx_conflict`. Send `replace_mx: true` when you do mean to move that mail.

## How do you check that it worked?

Check a domain's setup from two sides: ask the provider to verify, and look at public DNS yourself. With Trotta Mail, the verify call checks DNS again and reports on each record:

```bash
curl -s -X POST https://api.trotta.email/v1/domains/dom_2Yq5hLf6/verify \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  | jq '{status, records: [.records[] | {purpose, status, found}]}'
```

Each record comes back `ok`, `missing` or `wrong`. `wrong` means something else is published at that name, and `found` lists what. The domain is `verified` once the ownership and inbound records are in place, and a `domain.verified` event is sent. Publish the SPF, DKIM and DMARC records as well before an agent sends from the domain.

Then confirm what the rest of the internet sees:

```bash
dig +short MX agents.trotta.io
dig +short TXT agents.trotta.io
dig +short TXT _dmarc.agents.trotta.io
```

DNS changes take time to spread, so a record published a moment ago may not show everywhere at once. The verify call asks the zone's own name servers first, so it sees a new record early.

Last, create an inbox on the domain:

```bash
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "riley", "domain": "agents.trotta.io"}'
```

Or the whole flow in TypeScript:

```typescript
import { TrottaMail } from "trotta-mail";

const mail = new TrottaMail({ apiKey: process.env.TROTTA_MAIL_API_KEY });

const domain = await mail.domains.create({ name: "agents.trotta.io" });
for (const record of domain.records) {
  console.log(record.purpose, record.type, record.name, record.value);
}

// After the records are published:
const checked = await mail.domains.verify(domain.id);
if (checked.status === "verified") {
  const riley = await mail.inboxes.create({ name: "riley", domain: "agents.trotta.io" });
  console.log(riley.address); // riley@agents.trotta.io
}
```

Finish with a real message. Send one to the new address from an outside mailbox and read it through the API.

## What happens to the domain if the plan changes?

A domain is paused, not deleted, when a plan stops covering it. Mail for it still arrives and is still screened. Sending from it answers `403 custom_domain_paused` until the plan covers it again, and nothing has to be set up twice.

- Developer and Startup can add one more domain at a time as an add-on, $2 a month each.
- A platform can give each customer a domain of its own: a domain in a pod is for that pod's inboxes. See [multi-tenant agent inboxes](https://trotta.email/learn/multi-tenant-agent-inboxes).
- Humans can have a mailbox on the same domain, in the browser.

The [domain docs](https://trotta.email/docs/domains) walk through the console, and [pricing](https://trotta.email/pricing) lists what each plan includes.

## Questions

### Do I have to move my company email to put agents on my domain?

No. Put the agents on a subdomain. MX records apply to one exact name, so mail for the main domain keeps going where it goes today.

### What is the difference between MX and SPF records?

MX is for mail coming in: it names the servers that accept mail for the domain. SPF is for mail going out: it lists who may send for the domain, so receivers can check.

### Can I use my own domain on the Free plan?

No. Addresses on Free are at trotta.email. Your own domain is on paid plans: up to 3 on Developer at $20 a month, and up to 25 on Startup at $200 a month.

### Can I connect a mail client to an inbox on my domain over IMAP?

No. Trotta Mail has no IMAP or SMTP access for mail clients. Agents use the API, the MCP server or the SDK, and humans use the mailbox in the browser.

### How long does a domain take to verify?

It depends on your DNS provider. The verify call asks the zone's own name servers first, so it can see a record soon after you publish it.

## Sources

- [RFC 5321: Simple Mail Transfer Protocol (MX lookup)](https://www.rfc-editor.org/rfc/rfc5321)
- [RFC 7208: Sender Policy Framework (SPF)](https://www.rfc-editor.org/rfc/rfc7208)
- [RFC 6376: DomainKeys Identified Mail (DKIM) Signatures](https://www.rfc-editor.org/rfc/rfc6376)
- [RFC 9989: Domain-Based Message Authentication, Reporting, and Conformance (DMARC)](https://www.rfc-editor.org/rfc/rfc9989)

## Related

- [Connect a domain](https://trotta.email/docs/domains) Docs
- [SPF, DKIM and DMARC explained](https://trotta.email/learn/spf-dkim-dmarc) Guides
- [Plans and limits](https://trotta.email/docs/plans) Docs
- [Pricing](https://trotta.email/pricing)
- [Multi-tenant agent inboxes: one isolated workspace per customer](https://trotta.email/learn/multi-tenant-agent-inboxes) Guides
- [Email spoofing](https://trotta.email/threats/email-spoofing) Threat library

Give your agent an inbox of its own. Free for two inboxes. No card.

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
