Custom email domains for AI agents: DNS setup and verification

Choose a domain for your agents

A dedicated subdomain such as agents.yourcompany.com keeps agent email separate from your company’s existing inboxes. Adding a receiving MX record changes where messages for that exact domain are delivered. Do not replace your company’s MX records unless you intend to move that email service.

Custom domains are email domains, not website addresses. They do not change where the Cyberpidgeon console is hosted. The beta allows up to five custom domains per account by default. The deployment administrator may configure another limit.

Add the domain and prove ownership

Sign in to the console or connect with your account key, open Domains, and select Add domain. Enter the domain without an email name or URL prefix. The API equivalent is:

curl -X POST 'https://cyberpidgeon.com/v1/domains' \
  -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"agents.yourcompany.com"}'

The response includes a domain ID and a TXT ownership record at _cyberpidgeon-verification.agents.yourcompany.com. Copy the returned value into DNS, then select Check DNS, or call POST /v1/domains/{domainId}/verify. TXT values are unique to each account’s request. A mailbox-scoped agent key cannot add, verify, or remove domains.

Keep the TXT record after verification. Ownership is rechecked regularly. If the record disappears, the domain stops being usable for sending and receiving until ownership is verified again.

Verify sending and receiving separately

Once ownership is proven and the provider is connected, the console shows the sending SPF and DKIM records and the receiving MX record returned for your domain. Copy every required record, including MX priority. Some DNS dashboards append your DNS zone to the host field; check the resulting record name before saving.

Select Check DNS after saving the records. Provider verification is asynchronous: a successful check request does not mean the domain is ready. Use GET /v1/domains/{domainId} or refresh the console to inspect the saved status. Background checks refresh active domains, and verification older than one hour cannot authorize mail.

Sending and receiving appear independently. Both must be verified before you can create a mailbox on the domain. A later sending or receiving failure blocks the affected direction. Consider a DMARC policy appropriate to your existing email setup; review its effect across your senders before changing it.

Current beta availability: domain registration and ownership verification are available. The platform’s provider connection is still awaiting activation; mail DNS records and live delivery depend on that connection. The console reports this as awaiting provider activation instead of showing a verified state.

Create an agent mailbox on the verified domain

In New mailbox, select your verified domain and enter the agent’s email name. Existing mailboxes keep their original addresses. Through the API, provide the domain ID:

curl -X POST 'https://cyberpidgeon.com/v1/mailboxes' \
  -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Research assistant","local_part":"assistant","domain_id":"YOUR_DOMAIN_ID"}'

The result contains assistant@agents.yourcompany.com and its first scoped agent key. Save the key when it is returned. Sending, reading, and replying use the same message API as shared-domain mailboxes; clients cannot choose a different sender address. Omitting domain_id creates a mailbox on the shared platform domain.

Disconnect a domain safely

Use Remove domain in the console or DELETE /v1/domains/{domainId}. The domain is disconnected locally, its mailboxes are paused, and messages awaiting their first send are cancelled. Previously attempted messages with an unknown outcome are marked uncertain. Message history remains in the original account. A message already being sent may complete delivery and record its result.

Provider cleanup retries in the background if necessary. Once removal completes, remove the Cyberpidgeon DNS records you added. Reconnecting a domain starts a fresh verification process; old mailbox addresses and history are not transferred or recycled to another account.