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

Soft-deletes a message to trash or permanently purges it. Use label to detach from a single label.

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

messageId*string

Message ULID identifier

Query Parameters

label?string

Remove message from this specific label only

purge?string

Set to 'true' to permanently delete message immediately instead of moving to trash

Value in"true""false"

Response Body

Message deletion result

application/json
  1. response
blobOrphaned?boolean

True if message blob was permanently deleted from storage

deleted?boolean

True if message was deleted

expunged?boolean

True if the message was expunged (Recently deleted tier)

expungedAt?integer

Timestamp when the message was expunged, in epoch seconds

Formatint64
purgeAfter?integer

Timestamp when message will be permanently purged

Formatint64
purged?boolean

True if message was permanently purged

removedFromLabel?string

Label name the message was removed from

Example Request
curl -X DELETE 'https://api.open.email/api/v1/mailboxes/string/messages/string'
Example Response
{
  "blobOrphaned": true,
  "deleted": true,
  "expunged": true,
  "expungedAt": 0,
  "purgeAfter": 0,
  "purged": true,
  "removedFromLabel": "string"
}