---
title: "Mark messages as read or unread"
method: PATCH
path: "/api/emails/{address}/messages/read"
tags: ["Email"]
---

# Mark messages as read or unread

`PATCH /api/emails/{address}/messages/read`

## Request

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

Compatibility endpoint for retry-safe read-state updates. Returns the canonical durable per-item operation receipt plus the legacy count. Supply and reuse the `Idempotency-Key` header or compatibility `idempotency_key` field after timeouts.

## Path parameters

- `address` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `message_ids` string[], required: IDs of messages to mark
  - `read` boolean, required: true to mark as read, false to mark as unread
  - `idempotency_key` string

## Response `200`

Messages updated with durable receipt

- LegacyMailboxOperationReceipt: 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
  - `count` integer, required

## Other responses

- `400`: Invalid key, or header and body idempotency keys do not match
- `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)