Empty trash, or delete a batch of messages or whole conversations
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.
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
state?"expunged"Set to 'expunged' to permanently purge all trash messages
"expunged"purge?stringWhen deleting by IDs, set to 'true' to permanently purge instead of expunging to trash
"true""false"application/json- body
ids?array<string>Array of message IDs to delete
1 <= items <= 200threadExcludeRoles?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.
1 <= items <= 50threadLabel?stringThe 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.
1 <= lengththreadLabelOnly?booleanNarrow 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.
Purge count or batch deletion results
application/json- response
purgedCount*integerNumber of messages permanently removed from trash
int64curl -X DELETE 'https://api.open.email/api/v1/mailboxes/string/messages' \
-H 'Content-Type: application/json' \
-d '{}'{
"purgedCount": 0
}Append raw MIME message to mailbox POST
Stores raw RFC 5322 email bytes directly into a mailbox under a label without sending (similar to IMAP APPEND). Supports custom flags, Sieve filtering, and…
Get message metadata GET
Returns metadata for a specific message including subject, sender/recipients, labels, flags, UIDs, and timestamps.