Addresses & routing

How Inboundr decides what happens to an incoming email: address routes, store-only inboxes and the domain catch-all.

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

Routing order#

When a message arrives for local@yourdomain.com, Inboundr checks these in order:

An address route
If you created an address for that exact local part, its route applies. If the address has an endpoint, the message is delivered to that webhook. If it doesn't, the address is store-only: the message is kept for you to read, and no webhook is sent.
The domain catch-all
If there's no address route and the domain has a catch-all endpoint, the message is delivered there.
Stored by default
If neither applies, the message is still parsed and stored, and you can read it over the API and MCP. It just doesn't trigger a webhook.

An address route claims its address even when it has no endpoint. A store-only address is never sent to the catch-all.

Store-only or delivered#

Store-only

Leave out the endpoint. Mail is parsed and kept, and you read it with list_emails or the emails API. Suits agents that poll or read on demand.

Delivered

Attach a webhook endpoint. Each message is POSTed to your URL as a signed email.received event as it arrives.

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",
    "endpointIds": ["ep_123"]
  }'

The localPart is everything before the @: 1 to 64 characters, stored in lowercase. Leave out endpointIds, or pass [], for a store-only inbox. The single-endpoint form, "endpointId": "ep_123", is also accepted.

You don't need an address for every mailbox. With a verified domain, anything@yourdomain.com already receives mail. Create an address only when a specific mailbox needs its own routing.

One webhook per address#

An address delivers to one webhook endpoint, with its own deliveries and retries. If the mail needs to reach more than one system, fan it out from your own webhook handler.

Addresses API

Create, list, update and delete addresses.