Mailboxes
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
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
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
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:
identities.createisPOST /identities.identities.listisGET /identities; iterated withfor await, it is every mailbox of every page (Listings).mailboxes.getisGET /mailboxes/{mailboxId}.