# Receiving email

> Two ways to receive mail: real-time webhooks, or read on demand from stored inboxes.

Once a domain is [verified](/concepts/domains), it accepts mail on every address.
How you consume that mail is up to you.

## Option A — Webhooks (real time)

Best when you want to react the moment mail arrives.

<Steps>
  <Step title="Create an endpoint">
    ```bash
    curl https://inboundr.net/api/v1/endpoints \
      -H "Authorization: Bearer $INBOUNDR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Inbound handler", "url": "https://api.example.com/hooks/inbound" }'
    ```
    Save the returned `secret` — you'll use it to verify signatures.
  </Step>
  <Step title="Route mail to it">
    Route a single 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" }'
    ```
    …or catch **everything** on the domain:
    ```bash
    curl -X PATCH https://inboundr.net/api/v1/domains/dom_123 \
      -H "Authorization: Bearer $INBOUNDR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "catchAllEndpointId": "ep_123" }'
    ```
  </Step>
  <Step title="Handle the delivery">
    Inboundr POSTs a signed `email.received` payload to your URL. Verify the
    signature, then process the message. See the
    [payload structure](/webhooks/overview) and
    [signature verification](/webhooks/verifying-signatures).
  </Step>
</Steps>

## Option B — Read on demand (store-only)

Best for agents that read when they act, rather than running a server. Create a
store-only address (no `endpointId`) or just rely on catch-all with no endpoint
set — mail is parsed and stored either way.

```bash
# Newest inbound messages
curl "https://inboundr.net/api/v1/emails?direction=inbound&limit=20" \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"

# Everything sent to one address
curl "https://inboundr.net/api/v1/emails?to=support@yourdomain.com" \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"
```

Fetch a single message in full (bodies + attachment metadata) by id:

```bash
curl https://inboundr.net/api/v1/emails/em_abc123 \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"
```

<Tip>
  Agents can skip HTTP entirely and use the [MCP tools](/integrations/mcp)
  `list_emails`, `get_email`, and `get_thread` to read the same data.
</Tip>

## Choosing an approach

| | Webhooks | Read on demand |
| --- | --- | --- |
| Latency | Real time | When you poll / call |
| Needs a public URL | Yes | No |
| Best for | Servers, automations | Agents, scripts, batch |

You can use both — a store-only inbox is always readable even when it also
delivers to a webhook.