> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Inboxes and pods

> Create addresses for your agents, and isolate them per customer.

An inbox is an email address plus its own database. Each one is an independent store holding that address's threads, messages, drafts and lists — nothing is shared between inboxes, so one agent's conversations are never visible in another's queries.

The address **is** the identifier. There is no separate opaque id to map:

```
inbox_id = "ava@agent.waterr.ai"
```

Pass it directly in URLs. It needs no escaping in practice — `@` and `.` are both legal in a path segment.

## Creating an inbox

```bash theme={null}
curl -X POST "$BASE/v0/inboxes" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ava",
    "display_name": "Ava from Support",
    "client_id": "acct_8812"
  }'
```

| Field          | Notes                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `username`     | The local part. Omit it and a random one is generated.                                                |
| `domain`       | Defaults to `agent.waterr.ai`. Any other value must be a [verified domain](/agent-mailbox/domains).   |
| `display_name` | The friendly name on outbound mail — `Ava from Support <ava@agent.waterr.ai>`.                        |
| `pod_id`       | Places the inbox in a pod.                                                                            |
| `client_id`    | Your own identifier, stored and returned. Useful for mapping an inbox back to a row in your database. |

### Username rules

Letters, digits, dot, underscore and hyphen, up to 64 characters. Two constraints are worth knowing:

* **No `+`.** The plus sign is reserved for thread tokens — it is the mechanism that gets replies onto the right conversation. An address containing one would collide with it. See [how threading works](/agent-mailbox/messages#how-threading-works).
* **Unverified domains are rejected at creation.** Asking for an inbox on a domain the service cannot receive mail for returns `422`, rather than a `201` for an address that would silently never work.

## Listing, reading, updating

```bash theme={null}
# List (paginated)
GET /v0/inboxes?limit=50

# Read one
GET /v0/inboxes/ava@agent.waterr.ai

# Rename
PATCH /v0/inboxes/ava@agent.waterr.ai
{ "display_name": "Ava (Billing)" }

# Delete
DELETE /v0/inboxes/ava@agent.waterr.ai
```

A scoped key sees only the inboxes it was granted; the listing is filtered rather than refused.

<Warning>
  Deleting an inbox destroys its database — every thread, message and draft it holds. There is no undelete. If you only want it to stop receiving, remove its routing rule instead.
</Warning>

## Pods

A pod is a namespace for inboxes. It exists for multi-tenancy: when you run agents on behalf of your own customers, a pod per customer keeps their mail provably separate, and lets you hand out an API key that cannot see past its own pod.

```bash theme={null}
curl -X POST "$BASE/v0/pods" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-corp" }'
```

Then create inboxes inside it, and query across it:

```bash theme={null}
POST /v0/pods/pod_9k3mx.../inboxes      # create an inbox in the pod
GET  /v0/pods/pod_9k3mx.../inboxes      # every inbox in the pod
GET  /v0/pods/pod_9k3mx.../threads      # every thread across those inboxes
```

The pod-scoped thread listing is the one that earns pods their keep: it answers "show me everything happening for this customer" without your having to fan out across their inboxes and merge the results yourself.

### Pod-scoped keys

Issue a key with a `pod_id` and it can reach nothing outside that pod:

```bash theme={null}
curl -X POST "$BASE/v0/api-keys" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-agent", "pod_id": "pod_9k3mx..." }'
```

Webhooks created with that key are narrowed to the pod automatically, and WebSocket subscriptions are filtered against it. A tenant's agent cannot widen itself into another tenant's mail even if its own code asks to.

<Note>
  Deleting a pod that still contains inboxes is **refused** with `409 conflict`, naming how many are left. Delete the inboxes first. The guard is deliberate: a pod delete can never cascade into destroying a customer's mail history.
</Note>