For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
contact@agentmail.ccDiscord
DocumentationAPI ReferenceKnowledge BaseChangelog
DocumentationAPI ReferenceKnowledge BaseChangelog
  • Get Started
    • Welcome
    • Introduction
    • Quickstart
  • Core Concepts
    • Inboxes
    • Messages
    • Threads
    • Drafts
    • Labels
    • Lists
    • Attachments
    • Pods
    • Permissions
  • Integrations
    • Agent Onboarding
    • Skills
    • MCP
    • CLI
    • Google ADK
    • OpenClaw
    • Replit
    • x402
    • MPP
    • LiveKit
    • Sim.ai
  • Guides
    • Sending & Receiving Email
    • IMAP & SMTP
    • Multi-Tenancy
      • Creating Custom Domains
      • Managing Existing Domains
  • Webhooks
    • Overview
    • Events
    • Setup Guide
    • Verifying Webhooks
  • WebSockets
    • Overview
    • Quickstart
  • Best Practices
    • Email Deliverability
    • Idempotency
  • Examples
    • Github Repo Agent
    • Auto Reply Agent
    • Smart Labeling Agent
    • Sales Agent (WebSocket)
    • Live AgentMail Examples
  • Resources
    • FAQ
    • Talon Reply Extraction
    • Community
    • Support
LogoLogo
contact@agentmail.ccDiscord
On this page
  • Why Use a Custom Domain?
  • Setting Up Your Custom Domain
  • Troubleshooting Common DNS Issues
  • Best Practices for Domain Management
GuidesDomains

Using Custom Domains

Strengthen your agent's identity and improve deliverability with your own domain.
Was this page helpful?
Edit this page
Previous

Managing Your Domains

Best practices for monitoring, scaling, and optimizing your domain strategy for agent fleets.
Next
Built with

Why Use a Custom Domain?

When you’re deploying AI agents that send email at scale, deliverability and trust are paramount. While the default @agentmail.to domain is great for getting started, using your own custom domains is essential for production applications. It gives you control over your sending reputation and enables advanced strategies for high-volume outreach.

Improved Deliverability

Each domain builds its own sending reputation. By using your own domain, you control this reputation, which is the single most important factor in reaching the inbox.

Scale with Multiple Domains

For high-volume sending, register multiple domains (e.g., mercor.com, usemercor.com, mercorapp.com). Spreading email volume across them is a key strategy to maximize deliverability.

Setting Up Your Custom Domain

Configuring your domain is a three-step process: add the domain via API, copy the provided records into your DNS provider, and wait for verification.

1

1. Create Domain & Get DNS Records

Choose your preferred method to create a domain and get the required DNS records. AgentMail will register your domain and immediately return the full set of DNS records required for verification.

Console
SDK

Navigate to the AgentMail Console and follow these steps:

  1. Go to Domains Section: Click on “Domains” in the left sidebar
  2. Add New Domain: Click “Add Domain” or “Create Domain” button
  3. Enter Domain Name: Type your domain name (e.g., your-domain.com)
  4. Create Domain: Click “Create” to register the domain
2

2. Add Records to Your DNS Provider

The process for adding records varies slightly between providers. The examples below assume you are configuring records in the apex domain.com hosted zone. If you are using a subdomain make sure it is in the apex domain hosted zone.

Option A: Upload BIND Zone File (Easiest)

A BIND zone file is a text file that contains DNS resource records in a standardized format. This approach allows you to bulk upload our records to your DNS provider without you needing to go down one by one.

How to use the BIND zone file:

Step 1: Download the BIND zone file

After creating your domain in the AgentMail Console, click the “Download BIND Zone File” button to get the complete zone file.

Download BIND Zone File from Console
Downloading BIND zone file from AgentMail Console
Cloudflare
AWS Route 53
Porkbun

Step 2: Import to Cloudflare

  1. Go to your Cloudflare dashboard and select your domain
  2. Navigate to DNS > Records
Cloudflare BIND Import
This is what the page looks like
  1. Click “Import and Export”
Cloudflare BIND Import
You should be able to just drop the file in
  1. Upload the downloaded BIND zone file as is
BIND Zone File Format

Check that all records (TXT, MX) have been correctly imported in the console(the console will show in real time if we can find the records, typically within seconds).

Option B: Add Individual Records

Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The instructions vary depending on whether you’re using the AgentMail Console or the API directly.

Via Console
Via API

If you created your domain through the AgentMail Console, the DNS records are displayed in a simplified format that’s ready for copy-paste into your DNS provider.

Cloudflare
AWS Route 53

In the dashboard (DNS > Records), click “Add record”.

  • TXT (DMARC/SPF/DKIM):

    • Name: Copy the Name value directly from the console.
    • Content: Copy the Value from the console.

  • MX:

    • Name: Enter @ to apply the record to the root domain.
    • Mail server: Copy the Value from the console.
    • Priority: Use the priority shown in the console.
Console Advantage

The console automatically formats DNS record names to be relative hostnames (without the full domain), making them ready for direct copy-paste into your DNS provider. No manual parsing required!

3

3. Verify Your Domain

Once you’ve added the records, AgentMail automatically begins to check them. This can take anywhere from a few minutes to 48 hours for your DNS changes to propagate across the internet.

Check your domain verification status in the AgentMail Console:

  1. Navigate to Domains: Go to the “Domains” section in the left sidebar
  2. View Domain Status: Find your domain in the list and check its status
  3. Monitor Progress: The status will update automatically as verification progresses
  4. View Details: Click on your domain to see detailed information about which records are verified

The status indicators will show you exactly where you are in the process:

  • Not Started: You need to click the Verify Domain button to kick start the process
  • Pending: You still need to add or fix your DNS records
  • Invalid: Some of your records are misconfigured. Please verify you inputted them correctly.
  • Failed: Your records are correct, but our servers need a bump. Please click the verify domain button in the console.
  • Verifying: DNS records are correct, and we’re authorizing the domain
  • Verified: Domain is fully verified and ready for sending

Here are instructions for some common DNS providers. This list is not exhaustive, so please consult your provider’s documentation if you don’t see it here.

DNS/Hosting ProviderDocumentation Link
GoDaddyMX: Add an MX record
TXT: Add a TXT record
DreamHostHow do I add custom DNS records?
CloudflareMX: How do I add or edit mail or MX records?
TXT: Managing DNS records in Cloudflare
HostGatorManage DNS Records with HostGator/eNom
NamecheapMX: How can I set up MX records required for mail service?
TXT: How do I add TXT/SPF/DKIM/DMARC records for my domain?
Names.co.ukChanging your domain’s DNS settings
WixMX: Adding or Updating MX Records in Your Wix Account
TXT: Adding or Updating TXT Records in Your Wix Account
Ready to Go!

Once your domain status is ready, you can start creating Inboxes with your custom domain and building your agents!

Troubleshooting Common DNS Issues

DNS can be tricky. Here are some common issues and how to resolve them.

My DNS changes aren't showing up instantly

DNS propagation can take up to 48 hours, though it’s often much faster. If it’s been a while, click the verify domain button in the console which will trigger a reverification manually(DNS propagation can get stuck at times).

I'm seeing 'Too many SPF records' errors

A domain must have only one SPF record. If you’re using other services that send email on your behalf (like a CRM), you need to merge their SPF policies with AgentMail’s into a single record.

An SPF record is a single line of text. It starts with v=spf1 and ends with a mechanism like ~all or -all. All your permitted senders go in the middle.

How to Merge:

  1. Find your existing SPF record. It will look something like this: v=spf1 include:_spf.other-domain.com ~all
  2. Find AgentMail’s SPF include. This is include:spf.agentmail.to.
  3. Combine them. Copy the include from AgentMail and place it into your existing record, right before the ~all or -all part.
Example: Merging SPF records
# Before
v=spf1 include:_spf.other-domain.com ~all
# After
v=spf1 include:_spf.other-domain.com include:spf.agentmail.to ~all

Just keep adding include: mechanisms for each service you use. Remember to only have one v=spf1 at the beginning and one ~all or -all at the end.

Best Practices for Domain Management

Check out our guide on Email Deliverability for tips on warming up your new domain and maintaining a healthy sender reputation.