Email addresses

See the Email addresses guide for the fields in detail.

Endpoint	What it does
GET /inboxes	Every email address on the account, each with its unreadCount: unread mail in the inbox folder.
POST /inboxes	Create an address. Send a client-generated id (ibx_…), a domain, and a prefix (the server adds a random ending), a style (the server rolls a name), or a localPart: a rolled name on every plan, any name from Scale. Optional publicKey, meta and retentionDays (1 to 90, default 7). Every address counts toward the plan, and a full plan is 402 allocation_exhausted. A name that is taken or reserved is 409 address_taken. An account can create twice its allowance a day, and at least 25.
PATCH /inboxes/:id	Update the sealed label (meta) or retentionDays. A shorter window applies to mail already stored. publicKey adds the key to an address created without one: a session only (403 session_required for an API key), and once, so a different key is 409 public_key_set.
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/names	Up to eight rolled names that are free on a domain, as names. ?style= is person, business, team or neutral, and ?domain= is required. At most 300 an hour.
GET /inboxes/allocation	How many addresses the plan allows (limit), how many are assigned, how many more you can create (available), and whether the plan lets you choose names (customAddresses).
POST /workers/:id/inboxes	Assign an address to a device by inboxId. On Free a device holds one (402 plan_capability_required). An address on another device is 409 already_assigned. Session only.
DELETE /workers/:id/inboxes/:inboxId	Unassign an address from a device. It stays on the account and still counts. Session only.
GET /domains	Domains this account can create addresses on, as domains, each with domain, reserved (true for a domain that is only this account’s) and tier, the plan group a shared domain belongs to (null when reserved).
GET /domains/custom	Your own domains and the setup step each is on.
POST /domains/custom	Add a domain you own: 10 on Scale, 50 on Fleet (402 domain_limit_reached past that). Returns the TXT record that proves ownership. A domain already on Mailcycle is 409 domain_unavailable.
POST /domains/custom/:domain/check	Check the TXT record and nameservers again. At most 60 an hour.
DELETE /domains/custom/:domain	Remove one of your own domains. Refused with 409 domain_in_use 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" },
  "receives": true,
  "keyEpoch": 0
}

status is active on a device, unassigned otherwise, and suspended if Mailcycle has suspended the address. assignedWorkerId is left out when no device holds it. receives is false for an address created without its public key, which refuses mail until the key is added. pausedAt is set while paused after a missed payment. keyEpoch is the key epoch new mail is sealed under; see Teams.

“Session only” endpoints answer 403 session_required to an API key.