Email addresses

See the Email addresses guide for the fields in detail.

Endpoint	What it does
GET /inboxes	Every email address on the account.
POST /inboxes	Create an address. Send a client-generated id (ibx_…), a domain, and a prefix (the server adds a random ending) or, from Scale, a localPart. Optional publicKey, meta and retentionDays (1 to 90, default 7). Every address counts toward the plan.
PATCH /inboxes/:id	Update the sealed label (meta) or retentionDays. A shorter window applies to mail already stored.
DELETE /inboxes/:id	Delete an address with its mail and attachments, freeing its place on the plan. The address is retired and never reissued.
GET /inboxes/allocation	How many addresses the plan allows, how many are assigned, and how many more you can create.
POST /workers/:id/inboxes	Assign an address to a device by inboxId. On Free a device holds one.
DELETE /workers/:id/inboxes/:inboxId	Unassign an address from a device. It stays on the account and still counts.
GET /domains	Domains this account can create addresses on.
GET /domains/custom	Your own domains and the setup step each is on.
POST /domains/custom	Add a domain you own (Scale and up). Returns the TXT record that proves ownership.
POST /domains/custom/:domain/check	Check the TXT record and nameservers again.
DELETE /domains/custom/:domain	Remove one of your own domains. Refused while addresses exist on it.

An address returns:

{
  "id": "ibx_k3v9x2mq7a",
  "operatorId": "acct_…",
  "emailAddress": "receipts-x7k2@example-pool.email",
  "status": "active",
  "createdAt": "2026-09-18T09:00:00.000Z",
  "assignedWorkerId": "wkr_…",
  "retentionDays": 7,
  "pausedAt": null,
  "meta": { "…": "sealed" }
}

status is active on a device, unassigned otherwise. pausedAt is set while paused after a missed payment.