Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/labels

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Query Parameters

name?string

Exact label name for a read-authorized statistics query; no wildcard expansion

Length1 <= length <= 255

Response Body

List of labels

application/json
  1. response
labels*array<>

All labels visible to this caller

scheduledPending?integer

Number of sends scheduled and not yet released. Present only for the owner identity; absent (not zero) for a shared-mailbox viewer.

Formatint64
Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/labels'
Example Response
{
  "labels": [
    {
      "bytes": 52428800,
      "color": null,
      "deletedCount": 0,
      "highestModseq": 91842,
      "id": 1,
      "isSubscribed": true,
      "messageCount": 128,
      "name": "INBOX",
      "role": "inbox",
      "sortOrder": 0,
      "uidNext": 4214,
      "uidValidity": 1722470400,
      "unseenCount": 3
    },
    {
      "bytes": 18874368,
      "color": null,
      "deletedCount": 0,
      "highestModseq": 91842,
      "id": 2,
      "isSubscribed": true,
      "messageCount": 431,
      "name": "Sent",
      "role": "sent",
      "sortOrder": 1,
      "uidNext": 887,
      "uidValidity": 1722470400,
      "unseenCount": 0
    },
    {
      "bytes": 2097152,
      "color": "#4a90e2",
      "deletedCount": 0,
      "highestModseq": 91710,
      "id": 7,
      "isSubscribed": true,
      "messageCount": 41,
      "name": "Receipts",
      "role": null,
      "sortOrder": 6,
      "uidNext": 42,
      "uidValidity": 1722470400,
      "unseenCount": 0
    }
  ],
  "scheduledPending": 1
}