# List mailbox labels and folder statistics

Returns all system and custom labels with message counts, unread counts, UID validity, and next UID sequence numbers. Listing requires the lookup (`l`) right. With `name`, returns only that exact label's statistics and requires read (`r`) instead, so a reader can check a known folder without enumerating the mailbox. An unknown or out-of-scope name returns an empty labels array; wildcard characters are literal. For the owner identity, an unfiltered listing also reports how many sends are scheduled and not yet released, so a client can decide whether to offer a Scheduled view without a second request.

## `GET /api/v1/mailboxes/{mailboxId}/labels`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `name` (string, 1–255 chars) — Exact label name for a read-authorized statistics query; no wildcard expansion

### Responses

**200** — List of labels

`application/json` → LabelListPage

- `labels` (LabelInfo[], required) — All labels visible to this caller
  - `bytes` (integer <int64>, required) — Total storage size of live messages in this label in bytes
  - `color` (string | null, required) — Hex color code (#rrggbb) or null
  - `deletedCount` (integer <int64>, required) — Number of live messages marked with \Deleted flag
  - `highestModseq` (integer <int64>, required) — Current RFC 7162 HIGHESTMODSEQ change tracker for this label
  - `id` (integer <int64>, required) — Internal label numeric ID
  - `isSubscribed` (boolean, required) — True if folder is subscribed for client synchronization
  - `messageCount` (integer <int64>, required) — Total number of live messages in this label
  - `name` (string, required) — Label or folder name (e.g. INBOX, Archive, custom name)
  - `role` ("inbox" | "sent" | "drafts" | "trash" | "archive" | "junk", required) — System role if special folder, or null for custom user labels
  - `sortOrder` (integer <int64>, required) — Display sort order index for mailbox list
  - `uidNext` (integer <int64>, required) — Next message UID that will be assigned in this label
  - `uidValidity` (integer <int64>, required) — IMAP UIDVALIDITY epoch for this label
  - `unseenCount` (integer <int64>, required) — Number of unread messages in this label
- `scheduledPending` (integer <int64>) — Number of sends scheduled and not yet released. Present only for the owner identity; absent (not zero) for a shared-mailbox viewer.

**400** — validation_failed — malformed name

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**503** — 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)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/labels' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.labels.list`](/docs/sdks/typescript/labels/list)

```ts
const labelListPage = await openemail.labels.list(mailboxId)
```
