Skip to main content
The Email API manages the configuration behind agents that answer email: the custom domains you send and receive from, the inbound addresses that route mail to an agent, and the unsubscribe ledger that suppresses future sends. Every route lives under the /core prefix and is scoped per organization. For how email agents work end to end, see /email/overview. For tokens and the X-Anyreach-Org header, see /api-reference/authentication.

​
Base URL and auth

Send Authorization: Bearer <token> on every request. User personal access tokens (pat_) must also send X-Anyreach-Org: <organization_id>; organization API keys (ak_) carry their org implicitly. Each endpoint additionally requires the scope listed below.

​
Endpoints

​
Email domains

A domain registers a custom sending and receiving domain with the email provider (Resend) and tracks its DNS verification status. Creating a domain calls the provider and returns the dns_records you must publish. POST /email-domains accepts:
verify initiates verification and records verification_initiated_at. refresh only re-reads status and does not re-initiate, which makes it the right call for a passive status check.

​
Email addresses

An email address routes inbound mail to a specific agent. The address must be on the default inbound domain or on a domain your organization has already verified. POST /email-addresses accepts: PATCH /email-addresses/{address_id} accepts inbound_agent_version_id, outbound_from_address, and enabled. Only the fields you send are changed; sending inbound_agent_version_id: null explicitly unassigns the agent.
If the address is on a non-default domain that the organization has not verified, POST /email-addresses returns 400. Add and verify the domain under email domains first.

​
Unsubscribes

The unsubscribe ledger holds suppressed recipients. Suppressions are added automatically on STOP keywords, bounces, and complaints; deleting a row resubscribes that recipient.

​
Messaging preview

A dry-run render used by the agent editor’s live preview. It does not send anything. POST /messaging/preview accepts:
Scopes ending in :read are also satisfied by the matching :manage scope, and agents:read is satisfied by agents:manage.

​
Errors

​
Provider webhooks

Two endpoints receive callbacks from the email provider (Resend). They are signature-verified and dispatched by event type; they are not part of your authenticated surface and you do not call them. Both verify the request signature against the provider adapter and return 403 on an invalid signature. They use neither bearer tokens nor scopes, so do not send them traffic.

Email overview

How email agents receive, thread, and reply to mail.

Authentication

Tokens, scopes, and the X-Anyreach-Org header.