> ## 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 addresses

> Create inbound agent mailboxes and route them to an agent.

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](/email/connecting-a-domain).

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

## 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](/email/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

<Steps>
  <Step title="Choose the address">
    Pick a local part (letters, numbers, and hyphens only) and a domain — either `agents.anyreach.ai` or a verified custom domain.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set the reply-from and toggle">
    Optionally set `outbound_from_address` for replies, and leave `enabled` on so the agent answers immediately.
  </Step>
</Steps>

```bash theme={null}
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
  }'
```

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

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

```bash theme={null}
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.                                       |

## Related

<CardGroup cols={2}>
  <Card title="Connecting a domain" icon="globe" href="/email/connecting-a-domain">
    Add and verify a custom domain so you can use it for inbound addresses.
  </Card>

  <Card title="Configuring an email agent" icon="robot" href="/email/configuring-an-email-agent">
    Set up the agent that answers mail delivered to an address.
  </Card>
</CardGroup>