---
title: Custom Domain Setup
description: Configure a custom domain for branded email with Agentry.
surface: agent
---

## Choosing a Domain

We recommend using a **subdomain** for Agentry rather than your root domain. This lets you keep your existing email provider (Gmail, Outlook, etc.) on the root domain while Agentry handles agent email on the subdomain.

| Setup | Example | Notes |
|-------|---------|-------|
| Subdomain (recommended) | `agents.acme.com` | Keeps existing email on `acme.com` intact |
| Root domain | `acme.com` | Replaces all email handling — only use if this domain is dedicated to Agentry |

If you use the root domain, all MX traffic for that domain will route to Agentry. You cannot run another email service (Gmail, etc.) on the same domain simultaneously.

## Step 1: Register the Domain

```typescript
const domain = await client.domains.create({
  domain: "agents.acme.com",
});

// The response includes all DNS records you need to configure
console.log(domain.records);
```

Or via curl:

```bash
curl -X POST https://api.agentry.to/agent/v0/domains \
  -H "Authorization: Bearer ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "agents.acme.com"}'
```

## Step 2: Add DNS Records

The response includes all required DNS records. Add every record to your DNS provider.

| Type | Name | Value | Priority | Purpose |
|------|------|-------|----------|---------|
| MX | `agents.acme.com` | `inbound-smtp.us-east-1.amazonaws.com` | 10 | Routes inbound email to Agentry |
| TXT | `agents.acme.com` | `v=spf1 include:amazonses.com ~all` | — | Authorises Agentry to send email |
| TXT | `_dmarc.agents.acme.com` | `v=DMARC1; p=none` | — | DMARC policy |
| CNAME | `token1._domainkey.agents.acme.com` | `token1.dkim.amazonses.com` | — | DKIM signing (×3) |

### DNS Provider Tips

Different providers label fields differently:

- **Name vs Host:** Some providers (Namecheap, GoDaddy) use "Host" and auto-append your domain. For example, enter `agents` instead of `agents.acme.com`. The Agentry dashboard has a Name/Host toggle to show both formats.
- **MX Priority:** Most providers have a separate Priority field for MX records. Enter `10` in the Priority field and just the server address as the Value — not `10 inbound-smtp...` combined.
- **Root domain records:** If the Name is the same as your domain (e.g. the MX and SPF records), use `@` in the Host field.

## Step 3: Verify

After adding DNS records, trigger verification. DKIM propagation usually takes a few minutes but can take up to 72 hours.

```typescript
const verified = await client.domains.verify("dom_abc123");
console.log(verified.verification_status); // "verified" or "pending"
```

Once verified, a receipt rule is automatically created to accept inbound email for your domain.

## Step 4: Create Inboxes

```typescript
const inbox = await client.inboxes.create({
  username: "support",
  domain: "agents.acme.com",
  display_name: "Support Agent",
});
// Inbox address: support@agents.acme.com
```

## Pod-scoped domains

If you organize mailboxes by pod, use pod-scoped domain routes so the domain is attached to a specific pod context:

- `POST /agent/v0/pods/{pod_id}/domains`
- `GET /agent/v0/pods/{pod_id}/domains`
- `GET /agent/v0/pods/{pod_id}/domains/{domain_id}`
- `PATCH /agent/v0/pods/{pod_id}/domains/{domain_id}`
- `DELETE /agent/v0/pods/{pod_id}/domains/{domain_id}`
- `POST /agent/v0/pods/{pod_id}/domains/{domain_id}/verify`
- `GET /agent/v0/pods/{pod_id}/domains/{domain_id}/zone-file`

The DNS and verification workflow is the same; only the resource scope differs.

## Troubleshooting

**Verification stuck on "pending":**
- Double-check CNAME records are correct. A common mistake is entering the full name (e.g. `token._domainkey.agents.acme.com`) in a Host field that auto-appends the domain, resulting in `token._domainkey.agents.acme.com.acme.com`.
- Use `dig CNAME token._domainkey.agents.acme.com` to verify records are resolving.

**Emails bouncing with "mailbox unavailable":**
- Ensure the MX record is set up — DKIM verification can succeed without it, but email delivery requires it.
- Check that the domain identity exists in your cloud provider (this is created automatically by the API).

**Want to keep existing email on the root domain?**
- Use a subdomain for Agentry (e.g. `agents.acme.com`). MX records on the subdomain won't affect your root domain email.