Skip to Content
DELETE
/api/v1/mailboxes/{mailboxId}/messages

Permanently purges every row on the Recently-deleted tier with state=expunged, or deletes the messages named by ids and/or the conversations named by threadIds. These are the only two gestures in the API that cannot be undone by moving mail back (purge=true destroys; without it the rows drop to the Recently-deleted tier and age out), so a conversation named here MUST also carry threadLabel, the folder it was being viewed in. Omitting it is thread_context_required, never a default: a conversation routinely has one member in Trash and another still in the Inbox, and a Trash-view delete that expanded to the default set would take the Inbox copy with it. threadIds names LIVE conversations only — the Recently-deleted tier has no conversation view, so purging rows there is an ids gesture.

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

state?"expunged"

Set to 'expunged' to permanently purge all trash messages

Value in"expunged"
purge?string

When deleting by IDs, set to 'true' to permanently purge instead of expunging to trash

Value in"true""false"

Request Body

application/json
  1. body
ids?array<string>

Array of message IDs to delete

Items1 <= items <= 200
threadExcludeRoles?array<>

Roles to exclude from thread expansion (e.g. ['sent', 'drafts']). Members carrying any label with one of these roles are omitted from the expanded conversation. Trash and Junk members are already left out by the default expansion, so naming them here changes nothing unless threadLabel is that folder, where it empties the set. Explicit ids are unaffected. If every member is excluded, the conversation contributes nothing, which is not an error.

threadIds?array<string>

Conversation IDs to delete, expanded server-side to the members visible in threadLabel — which is REQUIRED alongside this. Refused with thread_too_large past 1000 expanded messages rather than deleting part of a conversation.

Items1 <= items <= 50
threadLabel?string

The folder each conversation in threadIds was being viewed in — the same value passed to GET /threads/{threadId}?label=, so the delete reaches exactly the members that view rendered. Inside Trash that is the trashed members, inside Junk the junked ones; anywhere else it is the live members carrying neither label. Required with threadIds, and validated: an unknown folder is unknown_label, not a fall back to the default set.

Length1 <= length
threadLabelOnly?boolean

Narrow each conversation to the members FILED UNDER threadLabel, as on PATCH /messages. Without it a delete made in the Inbox also takes the Sent copy of your replies and any member filed elsewhere — they are all part of the conversation that view renders. Inside Trash it changes nothing: the trashed members are already exactly that set.

Response Body

Purge count or batch deletion results

application/json
  1. response
purgedCount*integer

Number of messages permanently removed from trash

Formatint64
Example Request
curl -X DELETE 'https://api.open.email/api/v1/mailboxes/string/messages' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
{
  "purgedCount": 0
}