Inboxes and pods

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 = "[email protected]"

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

Creating an inbox

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.
`display_name`	The friendly name on outbound mail — `Ava from Support <[email protected]>`.
`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.
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

# List (paginated)
GET /v0/inboxes?limit=50

# Read one
GET /v0/inboxes/[email protected]

# Rename
PATCH /v0/inboxes/[email protected]
{ "display_name": "Ava (Billing)" }

# Delete
DELETE /v0/inboxes/[email protected]

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

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.

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.

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:

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:

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.

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.

Getting Started

Building

Reference

Creating an inbox

Username rules

Listing, reading, updating

Pods

Pod-scoped keys

​Creating an inbox

​Username rules

​Listing, reading, updating

​Pods

​Pod-scoped keys

Creating an inbox

Username rules

Listing, reading, updating

Pods

Pod-scoped keys