How do I set up a custom domain?

Custom domains let your agent send emails from your brand (e.g., agent@yourcompany.com) instead of the default @agentmail.to. This improves deliverability and builds trust with recipients.

Steps

1. Add your domain in the AgentMail Console or via the API
2. Add the DNS records AgentMail provides to your DNS provider
3. Wait for verification
4. Create inboxes on your custom domain

Adding a domain

You can add a domain through the AgentMail Console (go to Domains and click Add Domain) or via the API:

import { AgentMailClient } from "agentmail";
const client = new AgentMailClient({ apiKey: "am_..." });
// add your domain
const domain = await client.domains.create({ domain: "yourcompany.com" });
// view the DNS records you need to add
for (const record of domain.records) {
  console.log(`${record.type} | ${record.name} | ${record.value}`);
}

The response includes all the DNS records you need to add at your DNS provider.

DNS records you need to add

AgentMail returns the exact records for your domain in the AgentMail Console and in the records array of the Create Domain response. Always copy the values shown for your domain. For a US-region domain named example.com, the full set looks like this:

• SPF lives on mail.example.com, not your root domain. AgentMail sends with a custom MAIL FROM subdomain, and SPF is checked against that hostname. Do not add anything to an existing SPF record on your root domain (for example one for Google Workspace or Microsoft 365).
• The mail MX must be the only MX record at mail.example.com. If another MX record exists at that host, verification reports duplicate_records. This record carries bounces and complaints; it does not receive inbox mail.
• DMARC needs a reporting address. If _dmarc.example.com already has a DMARC record, keep that single record instead of adding a second one, and make sure it includes a rua=mailto: tag.
• DKIM needs exactly one TXT record at the selector host. Remove any older record at the same selector.
• Send-only domains: create the domain with inbound_enabled set to false and the receiving MX is left out, so your existing provider keeps receiving mail.
• Region: EU-region domains use eu-central-1 in the MX values in place of us-east-1.
• Subdomains: names are relative to your DNS zone. For agents.example.com, the hosts become agents, mail.agents, _dmarc.agents, and <selector>._domainkey.agents.
• Optional records: a link CNAME is added when tracking_enabled is on, and a wildcard * MX when subdomains_enabled is on.
• Older domains may show three DKIM CNAME records (<token>._domainkey pointing to <token>.dkim.amazonses.com) instead of one DKIM TXT record. Keep them if they already verify.

For step-by-step DNS setup instructions, see our provider guides: Cloudflare, GoDaddy, Route 53, Namecheap.

Verifying your domain

After adding DNS records, verify your domain:

await client.domains.verify(domain.domainId);

You can also verify from the AgentMail Console by navigating to the Domains section and clicking Verify Domain.

Verification status will progress through these stages:

Creating inboxes on your domain

Once verified, you can create inboxes using your custom domain:

const inbox = await client.inboxes.create({
  username: "support",
  domain: "yourcompany.com",
  displayName: "Support Agent",
});
console.log(`Created: ${inbox.inboxId}`);
// support@yourcompany.com

To create inboxes on any subdomain of your domain (e.g. support@bot.yourcompany.com) without registering each subdomain separately, enable subdomains on the domain and publish the wildcard MX record it returns.

Tips

• Use a subdomain (e.g., agents.yourcompany.com) if you don’t want to modify your root domain’s MX records or risk conflicts with existing email services. See MX record conflicts.
• Verification time varies by DNS provider, from a few minutes (Cloudflare, Route 53) to 30 minutes or more (GoDaddy, Namecheap)
• Leave your root SPF record alone: AgentMail’s SPF record goes on mail.yourcompany.com, not your root domain. Do not add include:agentmail.to or any other AgentMail value to an existing SPF record.

For a detailed walkthrough, see the Creating Custom Domains guide.