> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Run agent inboxes on your own domain instead of agent.waterr.ai.

Every inbox lives on `agent.waterr.ai` by default. Register your own domain to get addresses like `ava@support.yourcompany.com` instead.

```bash theme={null}
curl -X POST "$BASE/v0/domains" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "support.yourcompany.com" }'
```

The response lists the DNS records to publish. Publish them at your registrar, then verify:

```bash theme={null}
curl -X POST "$BASE/v0/domains/dom_9k3mxz7bd2vr8ncq4twf6hps/verify" \
  -H "Authorization: Bearer $KEY"
```

Verification checks your published records over DNS-over-HTTPS. On success the domain moves to `verified` and emits `domain.verified`. Only then can you create inboxes on it — an unverified domain is rejected at inbox creation with `422`, rather than handing you a `201` for an address that could never receive mail.

```bash theme={null}
GET    /v0/domains
GET    /v0/domains/{domain_id}
DELETE /v0/domains/{domain_id}
```

## Use a subdomain, not your apex

Register `support.yourcompany.com`, not `yourcompany.com`.

Receiving mail at a domain means pointing its `MX` records at the mail provider. Your apex `MX` is almost certainly carrying your company's real email — Google Workspace, Microsoft 365, whatever your colleagues use every day. Repointing it moves *everyone's* mail, not just the agent's.

A subdomain is a separate DNS name with its own `MX`. It cannot affect the apex, so the blast radius of getting it wrong is one agent rather than your whole company.

<Warning>
  This is not a theoretical caution. Some providers offer a one-click "add the missing records" action that writes `MX` and `SPF` scoped to the apex, with no confirmation step. On a domain with live company mail, that single click takes email down for the entire organisation. Work at the subdomain level and verify your apex `MX` before and after any change.
</Warning>

## Sending versus receiving

The two directions have very different costs, and it is worth knowing which you actually need.

|                            | What it takes                              | Risk                                      |
| -------------------------- | ------------------------------------------ | ----------------------------------------- |
| **Send** as your domain    | `SPF`, `DKIM`, `DMARC` — all `TXT` records | Low. Adding `TXT` records breaks nothing. |
| **Receive** at your domain | `MX` records                               | High at the apex, low at a subdomain.     |

If you only need the agent's mail to *appear* to come from your brand, send-only is much the safer configuration: publish the `TXT` records on your existing domain, keep receiving on `agent.waterr.ai`, and touch no `MX` at all.

<Note>
  Custom domain support is currently limited by the underlying mail platform, which serves inbound mail only for zones it hosts. If your domain is not on a supported provider, receiving is not available yet — send-only still is. Ask when you [request access](/agent-mailbox/authentication#getting-a-key) and we will tell you which applies to your setup.
</Note>

## Verification timing

Propagation varies more than people expect. Cloudflare and Route 53 typically publish within a minute or two; some registrars take 30 minutes or more.

Call `/verify` again rather than assuming failure — it re-checks live DNS each time, so there is no cost to polling it every few minutes until it passes.