Skip to main content
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:
FieldWhat it does
agent_idRoutes to the agent’s latest published version. The version is resolved at create time and pinned.
inbound_agent_version_idRoutes 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

FieldTypeDefaultDescription
addressstring—The full inbound mailbox address, for example support@agents.anyreach.ai. Local part is letters, numbers, and hyphens only. Required.
providerstringresendEmail provider for the address.
agent_idstringnoneAgent to answer this address; its latest published version is resolved and pinned.
inbound_agent_version_idstringnoneSpecific agent version that answers this address. Takes precedence over agent_id.
outbound_from_addressstringthe addressSender used for replies (reply-from). Defaults to the inbound address itself.
enabledbooleantrueWhether 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

1

Choose the address

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

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

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

MethodPathDescription
GET/core/email-addressesList addresses for the organization, each enriched with the routed agent’s id, name, and version.
POST/core/email-addressesCreate 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

ConstraintBehavior
Local part charactersLetters, numbers, and hyphens only; otherwise rejected.
DomainMust be agents.anyreach.ai or a verified custom domain, otherwise 400.
UniquenessGlobally unique across all organizations; duplicate returns 409.
RoutingRoutes 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.