Inboxes

An inbox is an address plus settings. Create one with POST /v0/inboxes (or POST /v0/pods/:pod_id/inboxes to place it in a pod).

curl -X POST "$BASE_URL/v0/inboxes" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"username": "billing", "display_name": "Billing Bot", "client_id": "billing-v1", "metadata": {"team": "finance"}}'

Field	Notes
`username`	Letters, digits and `. _ + -`, up to 64 characters. Random if omitted.
`domain`	A custom domain you have added; defaults to the service domain.
`display_name`	Shown in the From header.
`client_id`	Idempotency handle: creating twice returns the first inbox.
`status`	`active` (default) or `paused`.
`metadata`	Flat object of strings, numbers and booleans. Replaced as a whole by `PATCH`.

Addresses are unique across the service. A taken address returns 403 with code already_exists.

Pausing#

PATCH /v0/inboxes/:inbox_id with {"status": "paused"}:

Sends from the inbox fail with 403 inbox_paused.
Mail addressed to it is neither delivered nor bounced. It is dropped silently and produces no event.
Drafts scheduled to send while the inbox is paused fail and are not retried when you resume.

:inbox_id accepts the inbox id or the full address.

Deleting#

DELETE /v0/inboxes/:inbox_id removes the inbox with its messages and threads, the API keys scoped to it and its list entries. It returns 204, and keys scoped to it start answering 401. Do not send Content-Type: application/json on a request without a body: the server answers 400 bad_request.

Inboxes count against your plan (402 plan_limit_exceeded at the limit), so delete throwaway inboxes when you are done.