Manage email domains, addresses, and unsubscribes over HTTP.
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.
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.
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.
Method
Path
Scope
Description
GET
/email-domains
email_domains:read
List domains, newest first.
POST
/email-domains
email_domains:manage
Register a domain with the provider and return its DNS records.
GET
/email-domains/{domain_id}
email_domains:read
Fetch one domain.
POST
/email-domains/{domain_id}/verify
email_domains:manage
Initiate provider DNS verification, then store the result.
POST
/email-domains/{domain_id}/refresh
email_domains:read
Re-read the current provider status and records without re-initiating verification.
DELETE
/email-domains/{domain_id}
email_domains:manage
Remove the domain from the provider (best-effort) and delete the row.
POST /email-domains accepts:
Field
Type
Default
Description
domain
string
(required)
Custom domain, for example acme.com. Lowercased and validated.
provider
string
resend
Email provider.
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.
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.
Method
Path
Scope
Description
GET
/email-addresses
email_addresses:read
List addresses, enriched with the routed agent’s id, name, and version.
POST
/email-addresses
email_addresses:manage
Create an inbound routing address.
PATCH
/email-addresses/{address_id}
email_addresses:manage
Update routing, sender, or enabled state.
DELETE
/email-addresses/{address_id}
email_addresses:manage
Delete the address.
POST /email-addresses accepts:
Field
Type
Default
Description
address
string
(required)
Inbound mailbox address. The local part allows letters, numbers, and hyphens.
provider
string
resend
Email provider.
agent_id
string
null
Agent to answer this address; its latest published version is resolved. Alternative to inbound_agent_version_id.
inbound_agent_version_id
string
null
Specific agent version that answers mail to this address.
outbound_from_address
string
address
Verified sender used for replies. Defaults to address.
enabled
boolean
true
Serve the agent on this address.
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.
The unsubscribe ledger holds suppressed recipients. Suppressions are added automatically on STOP keywords, bounces, and complaints; deleting a row resubscribes that recipient.
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.
Method
Path
Description
POST
/messaging/webhook/{provider}
Inbound and status events for a provider, dispatched by event type.
POST
/messaging/status/{provider}
Delivery-status callbacks; also tolerates inbound events routed to it.
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.
