Custom Domain Setup

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

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:

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.

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

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.