# Addresses & routing

> How Inboundr decides what happens to an incoming message — explicit routes, store-only inboxes, and catch-all.

An **address** (also called an inbox) is a specific mailbox on one of your
domains, like `support@yourdomain.com`. Addresses control what happens when mail
arrives.

## Routing precedence

When a message arrives for `local@yourdomain.com`, Inboundr resolves it in this
order:

<Steps>
  <Step title="Explicit address route">
    If you created an address for that exact local part, its rule wins. If the
    address has an `endpointId`, the message is delivered to that webhook. If
    not, it's **store-only** (kept for retrieval, no webhook).
  </Step>
  <Step title="Domain catch-all">
    Otherwise, if the domain has a catch-all endpoint, the message is delivered
    there.
  </Step>
  <Step title="Store-only default">
    Otherwise the message is still parsed and stored — readable via the API and
    MCP — it just doesn't trigger a webhook.
  </Step>
</Steps>

<Note>
  An explicit address route claims that local part **either way** — even a
  store-only address (one with no endpoint) opts that address out of catch-all.
</Note>

## Store-only vs. delivered

<CardGroup cols={2}>
  <Card title="Store-only" icon="database">
    Omit `endpointId`. Mail is parsed and kept; read it with
    [`list_emails`](/integrations/mcp) / the
    [emails API](/api-reference/emails/list). Ideal for agents that poll or read
    on demand.
  </Card>
  <Card title="Delivered" icon="webhook">
    Set `endpointId` to a [webhook endpoint](/concepts/endpoints). Each message
    is POSTed to your URL as a signed `email.received` event in real time.
  </Card>
</CardGroup>

## Creating an address

```bash
curl https://inboundr.net/api/v1/addresses \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "dom_123",
    "localPart": "support",
    "endpointId": "ep_123"
  }'
```

The `localPart` is everything before the `@` (1–64 chars, lowercased). Omit
`endpointId` for a store-only inbox.

<Tip>
  You don't have to create an address for every mailbox. With catch-all on a
  verified domain, `anything@yourdomain.com` already works — create explicit
  addresses only when a specific mailbox needs different routing.
</Tip>

<Card title="Addresses API" icon="at" href="/api-reference/addresses/list">
  Create and list address routes.
</Card>

## Attaching a webhook

An address can attach to **one webhook endpoint**, which gets its own delivery
with its own retries.

```bash
curl https://inboundr.net/api/v1/addresses \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "domainId": "dom_123",
        "localPart": "support",
        "endpointIds": ["ep_agent_webhook"]
      }'
```

If you need to reach more than one destination, fan out from your own handler.

An empty `endpointIds` (or omitting it) makes the address **store-only** — mail
is kept and readable through the API and MCP, but nothing is delivered. The
single-destination `endpointId` spelling is still accepted and behaves as a list
of one.