Skip to Content

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:

OptionTypeSent asDescription
accountIdstringquery accountIdSystem callers only: list just this account's mailboxes (ignored for account principals, which always see their own)
state('deleted' | 'suspended')query statedeleted: 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 receiveHoldOnly 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
addressstringquery addressExact primary-address match (normalized) — the point lookup that saves a client walking the whole account to resolve one address. Live listing only
domainstringquery domainOnly mailboxes whose primary address is on this domain. Live listing only
qstringquery qCase-insensitive substring over the primary address. Live listing only
countbooleanquery countAlso 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
usagebooleanquery usageAlso 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
limitnumberquery limitPage size (default 100)
cursorstringquery cursorOpaque 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

StatusWhat it means
400validation_failed (also receiveHold with state=deleted); or account_required (state=suspended or receiveHold from a system key without accountId)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
503Identity 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 | IdentitiesListResultOption2

IdentitiesListResultOption1

/** 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.