Email addresses

An email address is an inbound mailbox that delivers mail to one agent. Each address routes to a single agent version, and when the agent replies it sends from a reply-from address you control.

Where addresses live

Every address has a local part and a domain. The local part may contain letters, numbers, and hyphens only — nothing else passes validation. The domain must be one of:

The default agents.anyreach.ai domain, available to every organization.
Any custom domain your organization has added and verified.

If you point an address at a non-default domain that is not verified for your organization, the create call is rejected with 400. Add and verify the domain first under Connecting a domain.

Addresses are globally unique. If the address is already in use — by your organization or any other — the create call returns 409.

Routing to an agent

An address routes to exactly one agent version. You can specify the target two ways:

Field	What it does
`agent_id`	Routes to the agent’s latest published version. The version is resolved at create time and pinned.
`inbound_agent_version_id`	Routes to a specific published agent version. Takes precedence over `agent_id`.

If you pass agent_id without inbound_agent_version_id, the latest published version of that agent is resolved and stored. If the agent has no resolvable published version, the call returns 400. Only published versions answer mail. Configure the agent itself — prompts, tools, reply behavior — under Configuring an email agent.

Fields

Field	Type	Default	Description
`address`	string	—	The full inbound mailbox address, for example `support@agents.anyreach.ai`. Local part is letters, numbers, and hyphens only. Required.
`provider`	string	`resend`	Email provider for the address.
`agent_id`	string	none	Agent to answer this address; its latest published version is resolved and pinned.
`inbound_agent_version_id`	string	none	Specific agent version that answers this address. Takes precedence over `agent_id`.
`outbound_from_address`	string	the address	Sender used for replies (reply-from). Defaults to the inbound address itself.
`enabled`	boolean	`true`	Whether the agent serves this address.

The outbound_from_address is the reply-from: when the agent answers, mail is sent from this address. Leave it blank to reply from the inbound address itself.

Create an address

Choose the address

Pick a local part (letters, numbers, and hyphens only) and a domain — either agents.anyreach.ai or a verified custom domain.

Pick the agent

Set agent_id to route to the agent’s latest published version, or inbound_agent_version_id to pin a specific published version.

Set the reply-from and toggle

Optionally set outbound_from_address for replies, and leave enabled on so the agent answers immediately.

curl -X POST https://api.anyreach.ai/core/email-addresses \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "support@agents.anyreach.ai",
    "agent_id": "<agent_id>",
    "outbound_from_address": "support@agents.anyreach.ai",
    "enabled": true
  }'

Org API keys (ak_) carry their organization implicitly and omit the X-Anyreach-Org header. User PATs (pat_) require it.

Update or unassign an agent

Send a PATCH to change the routed version, the reply-from, or the enabled toggle. Only the fields you include are changed; omitted fields are left untouched. To unassign the agent entirely, send inbound_agent_version_id explicitly set to null. The address stays, but no agent answers it.

curl -X PATCH https://api.anyreach.ai/core/email-addresses/<address_id> \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{ "inbound_agent_version_id": null }'

API reference

Method	Path	Description
`GET`	`/core/email-addresses`	List addresses for the organization, each enriched with the routed agent’s id, name, and version.
`POST`	`/core/email-addresses`	Create an inbound address.
`PATCH`	`/core/email-addresses/{address_id}`	Update the routed version, reply-from, or enabled state. Explicit `null` clears a field.
`DELETE`	`/core/email-addresses/{address_id}`	Delete the address.

Reading addresses requires the email_addresses:read or email_addresses:manage scope. Creating, updating, and deleting require email_addresses:manage.

Constraints

Constraint	Behavior
Local part characters	Letters, numbers, and hyphens only; otherwise rejected.
Domain	Must be `agents.anyreach.ai` or a verified custom domain, otherwise `400`.
Uniqueness	Globally unique across all organizations; duplicate returns `409`.
Routing	Routes to exactly one agent version.

Connecting a domain

Add and verify a custom domain so you can use it for inbound addresses.

Configuring an email agent

Set up the agent that answers mail delivered to an address.

Getting Started

Agents

Knowledge Bases

Telephony

Web Widgets

Email

Campaigns

Conversations

Evaluation & Metrics

Agent Assist

Workflows

Custom Data

Anyreach in Claude

Organizations & Billing

Where addresses live

Routing to an agent

Fields

Create an address

Update or unassign an agent

API reference

Constraints

Connecting a domain

Configuring an email agent

​Where addresses live

​Routing to an agent

​Fields

​Create an address

​Update or unassign an agent

​API reference

​Constraints

​Related

Connecting a domain

Configuring an email agent

Where addresses live

Routing to an agent

Fields

Create an address

Update or unassign an agent

API reference

Constraints

Related