Skip to main content
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"}'
FieldTypeDefaultDescription
domainstring—Required. The domain to register, lowercased and validated (for example acme.com).
providerstringresendEmail 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.
FieldTypeDescription
typestringRecord type, such as MX, TXT, or CNAME. The inbound MX record is what makes replies reach your agents.
namestringThe host/name to set at your registrar.
valuestringThe record value to publish.
prioritynumberPriority for MX records (lower wins). Absent on other types.
statusstringPer-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.
ActionEndpointWhat it doesWhen to use
VerifyPOST /core/email-domains/{domain_id}/verifyRe-initiates provider DNS verification, then re-reads status and records.After you first publish the records, or after fixing a record.
Refresh statusPOST /core/email-domains/{domain_id}/refreshA 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:
StatusMeaning
pendingVerification is in progress or not yet complete. One or more records have not resolved.
verifiedEvery record resolved. The domain can send and receive.
failedThe provider reported a verification failure. Re-check the records and verify again.

​
Scopes

OperationRequired scope
List, read, refreshemail_domains:read or email_domains:manage
Register, verify, deleteemail_domains:manage

​
Steps

1

Register the domain

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

Publish the DNS records

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

Verify

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

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.
5

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.