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.
openemail.identities.list(
options?: IdentitiesListOptions,
): PagePromise<IdentitiesListResult, MailboxWithUsage | DeletedMailbox>It calls GET /identities: List mailboxes in the API reference.
Example
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).
Answer
It is a listing, a PagePromise. Awaited, it is one page as the API answers it, IdentitiesListResult. Iterated with for await, it is every MailboxWithUsage | DeletedMailbox 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: its status, and its code, the API's error. Decide on the code: one status covers several.
Types
IdentitiesListResult
/** What `identities.list` answers. */
type IdentitiesListResult = IdentitiesListResultOption1 | IdentitiesListResultOption2IdentitiesListResultOption1
/** 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
/** 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, MailboxWithUsage.