Skip to Content

Create, list, and read mailboxes over the OpenEmail HTTP API.

A mailbox is the unit that receives and stores mail. It owns its messages, its quota, and its own credentials.

Paths are relative to https://api.open.email/api/v1, and every request carries a bearer credential — see Authentication.

Create a mailbox

POST /identities

curl -X POST "$API/identities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"primaryAddress": "you@example.com"}'

An identity is the account-scoped record that owns the mail store and its credentials, so creating, listing, updating, and deleting happen under /identities. The mail itself is read and sent under /mailboxes/{mailboxId}. Both families take the same id: the id this call returns is the mailboxId everywhere else.

primaryAddress is required unless you pass "withoutAddress": true. A create with neither answers 400 primary_address_required, and a create with both answers 400 without_address_has_address; either way nothing is written.

Passing primaryAddress is the common case, and it does more than set a label: the mailbox, the address-to-mailbox route, and the label are claimed atomically. The mailbox receives mail immediately, and an address already in use answers 409 with nothing created, so there is no half-built mailbox to clean up.

"withoutAddress": true creates an identity with no address and no mail store. It receives no mail, and the mail routes answer 404 for it, until you route an address to it through the routes API; that write gives it a mail store, and from then on it receives mail like any other mailbox. A domain-scoped API key cannot create one: it must always pass primaryAddress on one of its domains.

The rest of the body is send policy: a storage ceiling, daily message and recipient allowances, a recipient allowlist, and two separate ways to stop outbound — sendPaused holds it, sendDisabled turns it off.

List mailboxes

GET /identities

curl "$API/identities?domain=example.com&limit=25" \
  -H "Authorization: Bearer $TOKEN"

An account credential sees only its own mailboxes. Results are cursor paginated — pass the cursor from the previous page to continue.

Filters narrow by exact address, domain, or a search over addresses. Two parameters are worth knowing about because they change what the endpoint returns rather than which rows come back: count=true answers a count instead of rows, and state=deleted lists restorable tombstones instead of live mailboxes. That second one is how you find a mailbox you have deleted but not yet purged, while it is still inside its undo window.

Get a mailbox

GET /mailboxes/{mailboxId}

curl "$API/mailboxes/$MAILBOX_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns the mailbox with its usage stats. Answers 404 if the id does not resolve, or if your credential may not see it — the two are deliberately indistinguishable, so an unauthorized caller cannot probe for which ids exist.

Holding a mailbox app password, its mailbox's id is the mailboxId that GET /auth/whoami answers:

curl "$API/auth/whoami" -H "Authorization: Bearer $TOKEN"

In the TypeScript SDK

Each call above is a method of the TypeScript SDK: