Connecting a domain

A domain is the part after the @ in an agent’s email address. Register a custom domain to send and receive on your own brand (for example support@acme.com) instead of the default platform domain. Registration is one identity that both sends and receives, so verification publishes DKIM, SPF, and DMARC records for outbound mail plus an inbound MX record for replies. You don’t have to register anything to start. Every organization can use the default platform domain agents.anyreach.ai without verifying, so addresses like <name>@agents.anyreach.ai work out of the box. Register a custom domain only when you want mail to come from your own domain.

Domains are unique platform-wide. Registering a domain that another organization already holds returns 409 The domain <domain> is already registered.

Register a domain

Send the bare domain (no @, no subdomain prefix). The platform registers it with the email provider, enables receiving by default, and stores the DNS records you must publish.

curl -X POST https://api.anyreach.ai/core/email-domains \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

Field	Type	Default	Description
`domain`	`string`	—	Required. The domain to register, lowercased and validated (for example `acme.com`).
`provider`	`string`	`resend`	Email provider. Leave as the default.

The response includes the new domain with its status and the dns_records to publish:

{
  "id": "...",
  "domain": "acme.com",
  "provider": "resend",
  "status": "pending",
  "dns_records": [
    {
      "type": "MX",
      "name": "...",
      "value": "...",
      "priority": 10,
      "status": "pending"
    }
  ]
}

Publish the DNS records

Add every returned record at your DNS provider exactly as given, then verify. Each record carries its own status, and the domain only becomes usable once all records resolve. DNS changes can take a few minutes to several hours to propagate.

Field	Type	Description
`type`	`string`	Record type, such as `MX`, `TXT`, or `CNAME`. The inbound `MX` record is what makes replies reach your agents.
`name`	`string`	The host/name to set at your registrar.
`value`	`string`	The record value to publish.
`priority`	`number`	Priority for `MX` records (lower wins). Absent on other types.
`status`	`string`	Per-record verification state: `verified`, `pending`, or `failed`.

Records must stay in place to keep working. Removing a published record after verification breaks sending or receiving on the domain. Do not delete them once verified.

Verify vs. refresh

Two actions move a domain toward verified. They are different operations.

Action	Endpoint	What it does	When to use
Verify	`POST /core/email-domains/{domain_id}/verify`	Re-initiates provider DNS verification, then re-reads status and records.	After you first publish the records, or after fixing a record.
Refresh status	`POST /core/email-domains/{domain_id}/refresh`	A passive re-read of the current provider status and records. Does not re-initiate verification.	To re-check progress while DNS is still propagating.

# Re-initiate verification (use after publishing or fixing records)
curl -X POST https://api.anyreach.ai/core/email-domains/<domain_id>/verify \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"

# Passive re-read of status (use while waiting on propagation)
curl -X POST https://api.anyreach.ai/core/email-domains/<domain_id>/refresh \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>"

Verify after every DNS edit; refresh in between to watch records flip to verified without re-triggering the provider. Once the last record is verified, the whole domain reports verified.

Domain status

The domain status normalizes to one of three values regardless of the provider’s raw vocabulary:

Status	Meaning
`pending`	Verification is in progress or not yet complete. One or more records have not resolved.
`verified`	Every record resolved. The domain can send and receive.
`failed`	The provider reported a verification failure. Re-check the records and verify again.

Scopes

Operation	Required scope
List, read, refresh	`email_domains:read` or `email_domains:manage`
Register, verify, delete	`email_domains:manage`

Steps

POST /core/email-domains with the bare domain. The response returns status: pending and the dns_records to publish.

Publish the DNS records

Add every record (DKIM/SPF/DMARC plus the inbound MX) at your DNS provider, exactly as returned.

Verify

POST /core/email-domains/{domain_id}/verify to re-initiate provider verification.

Wait and refresh

While DNS propagates, POST /core/email-domains/{domain_id}/refresh to re-check without re-triggering. When the last record resolves, status becomes verified.

Create addresses

Once verified, create agent email addresses on the domain. See Email addresses.

Next steps

Email addresses

Create agent addresses on a verified domain or on agents.anyreach.ai.

Email overview

How agents send and receive email across the platform.

Getting Started

Agents

Knowledge Bases

Telephony

Web Widgets

Email

Campaigns

Conversations

Evaluation & Metrics

Agent Assist

Workflows

Custom Data

Anyreach in Claude

Organizations & Billing

Connecting a domain

Register a domain

Publish the DNS records

Verify vs. refresh

Domain status

Scopes

Steps

Next steps

Email addresses

Email overview

​Register a domain

​Publish the DNS records

​Verify vs. refresh

​Domain status

​Scopes

​Steps

​Next steps

Email addresses

Email overview

Register a domain

Publish the DNS records

Verify vs. refresh

Domain status

Scopes

Steps

Next steps