Delete a message (move to Trash, or expunge)
DELETE /v1/inboxes/{inbox_id}/messages/{id}
Move a message to the Trash folder (a recoverable soft delete). Pass ?expunge=true to permanently remove it instead. A message already in Trash is always expunged. Requires mailbox:read plus mailbox:create (or mailbox:delete); the owning agent’s default key carries both capabilities.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Opaque inbox id (the canonical path key). The inbox’s email address is also accepted here as a within-project alias. Treat the id as opaque.
Opaque message id (msg_...). Encodes its owning inbox.
Query Parameters
Section titled “Query Parameters ”Permanently remove instead of moving to Trash.
Responses
Section titled “ Responses ”Delete outcome.
Outcome of a message or thread delete.
object
The message id or thread id that was deleted.
Always true on success.
True when the message(s) were permanently removed; false when moved to Trash (a recoverable soft delete).
Number of messages affected (1 for a message; the thread size for a thread).
Invalid request.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMissing or invalid credential.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeAuthenticated but lacking the required scope, or out of quota.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeResource not found.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scope