# 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](/docs/guides/authentication).

## Create a mailbox

[`POST /identities`](/docs/api/mailboxes/post_IdentityCreate)

```bash
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`](/docs/api/mailboxes/get_IdentityList)

```bash
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}`](/docs/api/mailboxes/get_MailboxGet)

```bash
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`](/docs/api/credentials/get_AuthWhoami) answers:

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

## In the TypeScript SDK

Each call above is a method of the [TypeScript SDK](/docs/sdks/typescript):

- [`identities.create`](/docs/sdks/typescript/identities/create) is `POST /identities`.
- [`identities.list`](/docs/sdks/typescript/identities/list) is `GET /identities`;
  iterated with `for await`, it is every mailbox of every page
  ([Listings](/docs/sdks/typescript/listings)).
- [`mailboxes.get`](/docs/sdks/typescript/mailboxes/get) is `GET /mailboxes/{mailboxId}`.
