> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://www.agentmail.to/docs/llms.txt.

# 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.

> **Note**
>
> Custom domains are available on the **Developer plan and above**. The free tier uses `@agentmail.to` only. See the [pricing page](https://agentmail.to/pricing) for details.

## Steps

1. Add your domain in the [AgentMail Console](https://console.agentmail.to) 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](https://console.agentmail.to) (go to **Domains** and click **Add Domain**) or via the API:

**`TypeScript`**

```typescript title="TypeScript"
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

| Record       | Type | Purpose                                                                                       |
| ------------ | ---- | --------------------------------------------------------------------------------------------- |
| Receiving MX | MX   | Routes incoming mail for your domain to AgentMail                                             |
| MAIL FROM MX | MX   | Receives bounce and complaint notifications on `mail.yourcompany.com`                         |
| SPF          | TXT  | Authorizes AgentMail's sending servers for `mail.yourcompany.com`, the envelope sender domain |
| DKIM         | TXT  | Publishes the custom DKIM selector key used to sign your email                                |
| DMARC        | TXT  | Defines how receivers handle authentication failures                                          |

AgentMail returns the exact records for your domain in the [AgentMail Console](https://console.agentmail.to) and in the `records` array of the [Create Domain](https://docs.agentmail.to/api-reference/domains/create) response. Always copy the values shown for your domain. For a US-region domain named `example.com`, the full set looks like this:

| Purpose             | Type  | Name (host)             | Value                                               | Priority |
| ------------------- | ----- | ----------------------- | --------------------------------------------------- | -------- |
| Receiving           | `MX`  | `@`                     | `inbound-smtp.us-east-1.amazonaws.com`              | `10`     |
| Bounces (MAIL FROM) | `MX`  | `mail`                  | `feedback-smtp.us-east-1.amazonses.com`             | `10`     |
| SPF (MAIL FROM)     | `TXT` | `mail`                  | `v=spf1 include:amazonses.com -all`                 |          |
| DKIM                | `TXT` | `<selector>._domainkey` | `v=DKIM1; k=rsa; p=...` (your public key)           |          |
| DMARC               | `TXT` | `_dmarc`                | `v=DMARC1; p=reject; rua=mailto:dmarc@agentmail.to` |          |

* **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.

> **Note**
>
> Legacy orgs should keep existing working DNS records in place. For new domain setup, add the TXT selector records shown in the AgentMail Console or API response.

> **Note**
>
> If you only need to **send** from your custom domain, create it with `inbound_enabled` set to `false` (`inboundEnabled: false` in TypeScript). AgentMail then leaves the receiving MX out of the records, and your existing email provider keeps receiving mail. On a domain with receiving enabled, the receiving MX is required: verification does not complete without it.

For step-by-step DNS setup instructions, see our provider guides:
[Cloudflare](/knowledge-base/dns-cloudflare), [GoDaddy](/knowledge-base/dns-godaddy), [Route 53](/knowledge-base/dns-route53), [Namecheap](/knowledge-base/dns-namecheap).

## Verifying your domain

After adding DNS records, verify your domain:

**`TypeScript`**

```typescript title="TypeScript"
await client.domains.verify(domain.domainId);
```

You can also verify from the [AgentMail Console](https://console.agentmail.to) by navigating to the Domains section and clicking **Verify Domain**.

Verification status will progress through these stages:

| Status        | Meaning                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `NOT_STARTED` | You need to click Verify Domain to start the process                                            |
| `PENDING`     | DNS records still need to be added or fixed                                                     |
| `INVALID`     | Some records are misconfigured; double check the values                                         |
| `FAILED`      | Your records are correct, but verification needs another attempt; click **Verify Domain** again |
| `VERIFYING`   | DNS records are correct and authorization is in progress                                        |
| `VERIFIED`    | Domain is ready for sending and receiving                                                       |

## Creating inboxes on your domain

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

**`TypeScript`**

```typescript title="TypeScript"
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](/custom-domains#setting-up-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](/knowledge-base/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](/custom-domains) guide.