> ## Documentation Index > Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt > Use this file to discover all available pages before exploring further. # Email API > 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](/email/overview). For tokens and the `X-Anyreach-Org` header, see [/api-reference/authentication](/api-reference/authentication). ## Base URL and auth ``` https://api.anyreach.ai/core ``` Send `Authorization: Bearer ` on every request. User personal access tokens (`pat_`) must also send `X-Anyreach-Org: `; 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. | 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. ### 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. | 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. ### Unsubscribes The unsubscribe ledger holds suppressed recipients. Suppressions are added automatically on `STOP` keywords, bounces, and complaints; deleting a row resubscribes that recipient. | Method | Path | Scope | Description | | -------- | -------------------------------- | --------------------- | ------------------------------------------ | | `GET` | `/unsubscribes` | `unsubscribes:read` | List suppressions, newest first. | | `DELETE` | `/unsubscribes/{suppression_id}` | `unsubscribes:manage` | Resubscribe by removing a suppression row. | ### Messaging preview A dry-run render used by the agent editor's live preview. It does not send anything. | Method | Path | Scope | Description | | ------ | -------------------- | ------------- | ------------------------------------------------------ | | `POST` | `/messaging/preview` | `agents:read` | Render a sample message for a channel without sending. | `POST /messaging/preview` accepts: | Field | Type | Default | Description | | ----------------------- | ------ | ---------- | ------------------------------ | | `channel` | string | (required) | One of `email`, `text`, `sms`. | | `properties` | object | `{}` | Channel render properties. | | `sample_agent_response` | string | (sample) | Body text to render. | | `context` | object | `null` | Optional render context. | Scopes ending in `:read` are also satisfied by the matching `:manage` scope, and `agents:read` is satisfied by `agents:manage`. ## Errors | Status | When | | ------ | ---------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid body, a `PATCH` with no fields, or an address on an unverified non-default domain. | | `404` | The domain, address, or suppression id does not exist. | | `409` | Duplicate domain (already registered) or duplicate address (already in use). Addresses are unique across the platform. | | `502` | The email provider returned an error during create, verify, or refresh. | ## 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. | 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. ## Related How email agents receive, thread, and reply to mail. Tokens, scopes, and the X-Anyreach-Org header.