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:

1
import { AgentMailClient } from "agentmail";
2
3
const client = new AgentMailClient({ apiKey: "am_..." });
4
5
// Add your domain
6
const domain = await client.domains.create("yourcompany.com");
7
8
// View the DNS records you need to add
9
for (const record of domain.records) {
10
  console.log(`${record.type} | ${record.name} | ${record.value}`);
11
}

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

DNS records you need to add

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:

1
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:

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

Tips

• Use a subdomain (e.g., mail.yourcompany.com) if you don’t want to modify your root domain’s MX records or risk conflicts with existing email services
• Verification time varies by DNS provider, from a few minutes (Cloudflare, Route 53) to 30 minutes or more (GoDaddy, Namecheap)
• One SPF record per domain: if you already have an SPF record, merge AgentMail’s include: into the existing record rather than creating a second one For a detailed walkthrough, see the Creating Custom Domains guide.