---
title: "Apply a lifecycle action to messages"
method: POST
path: "/api/emails/{address}/messages/actions"
tags: ["Email"]
---

# Apply a lifecycle action to messages

`POST /api/emails/{address}/messages/actions`

## Request

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

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.

## Path parameters

- `address` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `message_ids` string[], required
  - `action` 'move' | 'mark_read' | 'star' | 'restore' | 'delete_permanently' | 'label', required
  - `destination` 'inbox' | 'archive' | 'sent' | 'spam' | 'trash'
  - `read` boolean
  - `starred` boolean
  - `add` string[]: label: labels to add
  - `remove` string[]: label: labels to remove
  - `set` string[]: label: replace every label (wins over add and remove)
  - `idempotency_key` string: Stable key for this exact logical batch. Reuse after a timeout.

## Response `200`

All requested actions completed; returns a durable receipt

- MailboxOperationReceipt: Durable, retry-safe receipt for a mailbox lifecycle batch.
  - `operation_id` string, required
  - `idempotency_key` string, required
  - `idempotent_replay` boolean, required: True when this response reused the immutable completed receipt and performed no new mutation.
  - `action` 'move' | 'mark_read' | 'star' | 'restore' | 'delete_permanently' | 'label', required
  - `status` 'succeeded' | 'partial', required
  - `results` object[], required
    - `message_id` string, required
    - `ok` boolean, required
    - `folder` 'inbox' | 'archive' | 'sent' | 'drafts' | 'spam' | 'trash'
    - `changed` boolean
    - `error` object
      - `code` string, required
      - `message` string, required
  - `summary` object, required
    - `total` integer, required
    - `succeeded` integer, required
    - `failed` integer, required
    - `changed` integer, required
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable, required

## Other responses

- `207`: Some message actions failed; inspect each per-item result
- `400`: Invalid key, or header and body idempotency keys do not match
- `403`: Permanent deletion requires email:delete
- `409`: Operation still processing, or idempotency key reused with a different request

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)