Apply a lifecycle action to messages

Move, restore, mark read, star, or permanently delete up to 100 explicit message IDs. Moving to Trash is reversible. Permanent deletion requires email:delete and only accepts messages already in Trash. Every response is a durable operation receipt with one result per requested ID. Supply a stable key in the standard Idempotency-Key header or legacy idempotency_key JSON field and reuse it after timeouts; an exact retry returns the stored receipt without another mutation. If both forms are supplied, they must match. Reusing a key with a different request returns 409. When omitted, the server creates a key and returns it in the body and Idempotency-Key header. Returns 207 when only part of the batch succeeds.

post/api/emails/{address}/messages/actions

Request

Base URL: https://domani.run
URL: https://domani.run/api/emails/{address}/messages/actions
Auth: HTTP bearer

Path parameters

addressstring required

Headers

Idempotency-Keystring

Stable key for this exact logical batch. Preferred over the compatibility JSON field.

Request body

message_idsstring[] required

destination'inbox' | 'archive' | 'sent' | 'spam' | 'trash'

readboolean

starredboolean

addstring[]

label: labels to add

removestring[]

label: labels to remove

setstring[]

label: replace every label (wins over add and remove)

idempotency_keystring

Stable key for this exact logical batch. Reuse after a timeout.

Response

All requested actions completed; returns a durable receipt

operation_idstring required

idempotency_keystring required

idempotent_replayboolean required

True when this response reused the immutable completed receipt and performed no new mutation.

status'succeeded' | 'partial' required

created_atstring date-time required

completed_atstring date-time nullable required

Changes

No recorded changes to this operation across all 2 revisions of this API.