Skip to Content
POST
/api/v1/mailboxes/{mailboxId}/labels/{label}/expunge

Detaches messages marked with the deleted flag from this label. Messages left with no remaining labels move to Recently deleted and can be restored until permanent purge.

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

label*string

Label or folder name (e.g. INBOX, Archive, custom)

Response Body

Expunged message list

application/json
  1. response
expunged*array<>

List of expunged message UIDs and IDs

messagesExpunged*integer

Total count of messages removed from this label

Formatint64
Example Request
curl -X POST 'https://api.open.email/api/v1/mailboxes/string/labels/string/expunge'
Example Response
{
  "expunged": [
    {
      "messageId": "string",
      "uid": 0
    }
  ],
  "messagesExpunged": 0
}