# identities.list

List mailboxes.

Lists mailboxes for the authenticated account. Set state=deleted to list restorable tombstones (deleted mailboxes still within the undo window). A SYSTEM caller lists every mailbox on the deployment, and may narrow to one tenant with `accountId`. Under the partitioned directory a system caller's deployment-wide listing walks the accounts in turn: its rows come account by account, its pages are bounded in work, so one may hold fewer than limit rows while more follow, and the list ends only when nextCursor is absent.

```ts
openemail.identities.list(
  options?: IdentitiesListOptions,
): PagePromise<IdentitiesListResult, MailboxWithUsage | DeletedMailbox>
```

It calls `GET /identities`: [List mailboxes](/docs/api/mailboxes/get_IdentityList) in the API reference.

## Example

```ts
for await (const mailboxWithUsage of openemail.identities.list()) {
  // every item of every page (await the call instead for one page)
}
```

## Options

The last argument, `options`, a `IdentitiesListOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `accountId` | `string` | query `accountId` | System callers only: list just this account's mailboxes (ignored for account principals, which always see their own) |
| `state` | `('deleted' \| 'suspended')` | query `state` | deleted: list restorable tombstones instead of live mailboxes. suspended: only live mailboxes the account owner has suspended, pending ones included (one account's listing: an account key, or a system key with accountId) |
| `receiveHold` | `('none' \| 'paused' \| 'disabled')` | query `receiveHold` | Only live mailboxes whose receiveHold is this value (none selects the receiving ones), pending ones included; combines with state=suspended. One account's listing: an account key, or a system key with accountId (400 account_required otherwise). With state=deleted it is refused (400 validation_failed) rather than ignored |
| `address` | `string` | query `address` | Exact primary-address match (normalized) — the point lookup that saves a client walking the whole account to resolve one address. Live listing only |
| `domain` | `string` | query `domain` | Only mailboxes whose primary address is on this domain. Live listing only |
| `q` | `string` | query `q` | Case-insensitive substring over the primary address. Live listing only |
| `count` | `boolean` | query `count` | Also return `total`: the full COUNT over the same filters, so 'N mailboxes on this domain' is one call instead of a walk. Opt-in because the default keyset page deliberately carries no totals |
| `usage` | `boolean` | query `usage` | Also return each row's SAMPLED storage (`usedBytes`, `trashBytes`, `pimBytes`, `messageCount`, `databaseSize`, `usageAt`, `usageStale`) from the daily usage ledger — ONE call for the whole page, never a per-row stat read. These are as of `usageAt`, not live: a mailbox the sweep has not reached yet omits them entirely, and a client must render that as blank rather than as zero. Live figures are GET /mailboxes/:id. Live listing only |
| `limit` | `number` | query `limit` | Page size (default 100) |
| `cursor` | `string` | query `cursor` | Opaque page cursor from a previous response |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

It is a listing, a [`PagePromise`](/docs/sdks/typescript/listings). Awaited, it is one page as the API answers it, [`IdentitiesListResult`](#identitieslistresult). Iterated with `for await`, it is every [`MailboxWithUsage`](/docs/sdks/typescript/types/mailbox-with-usage) | [`DeletedMailbox`](/docs/sdks/typescript/types/deleted-mailbox) of every page, each page fetched as the loop reaches it.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed (also receiveHold with state=deleted); or account_required (state=suspended or receiveHold from a system key without accountId) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `503` | Identity inventory temporarily unavailable; retry the same cursor. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### IdentitiesListResult

```ts
/** What `identities.list` answers. */
type IdentitiesListResult = IdentitiesListResultOption1 | IdentitiesListResultOption2
```

### IdentitiesListResultOption1

```ts
/** The API's `IdentitiesListResultOption1`, as the document describes it. */
type IdentitiesListResultOption1 = {
  identities: MailboxWithUsage[]
  /** Opaque cursor for the next page; absent on the last page */
  nextCursor?: string
  /** Full filtered COUNT — present only when count=true was requested */
  total?: number
}
```

### IdentitiesListResultOption2

```ts
/** The API's `IdentitiesListResultOption2`, as the document describes it. */
type IdentitiesListResultOption2 = {
  identities: DeletedMailbox[]
  /** Opaque cursor for the next page; absent on the last page */
  nextCursor?: string
}
```

It names these types of the API, each on a page of its own: [`DeletedMailbox`](/docs/sdks/typescript/types/deleted-mailbox), [`MailboxWithUsage`](/docs/sdks/typescript/types/mailbox-with-usage).
