Create a new custom label
Creates a new user folder or label with a fresh UID validity epoch.
bearerAuthAuthorizationBearer <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: [].
mailboxId*stringMailbox ULID identifier
application/json- body
color?|Hex color code for the label badge/chip, or null
^#[0-9a-f]{6}$name*stringName for the new label. May not start with *, which clients reserve for their own views
1 <= length <= 255Created label details
application/json- response
color*|Hex color code for the label badge/chip, or null
id*integerAssigned label ID
int64name*stringCreated label name
uidValidity*integerInitial UIDVALIDITY epoch for the label
int64curl -X POST 'https://api.open.email/api/v1/mailboxes/string/labels' \
-H 'Content-Type: application/json' \
-d '{
"name": "string"
}'{
"color": "string",
"id": 0,
"name": "string",
"uidValidity": 0
}Labels
Folders and labels: CRUD, per-label statistics, and the IMAP-shaped UID/vanished feeds a mail client syncs from.
List mailbox labels and folder statistics GET
Returns all system and custom labels with message counts, unread counts, UID validity, and next UID sequence numbers. Listing requires the lookup (`l`) right…