---
title: "Mark an email read or unread"
method: PATCH
path: "/v1/mailboxes/{mailbox_id}/emails/{email_id}"
tags: ["Emails"]
---

# Mark an email read or unread

`PATCH /v1/mailboxes/{mailbox_id}/emails/{email_id}`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes/{mailbox_id}/emails/{email_id}`
- Auth: HTTP bearer

Only read status can change.

## Path parameters

- `mailbox_id` string, required
- `email_id` string, required

## Query parameters

- `include_storage` boolean

## Request body

- object
  - `read` boolean, required
  - `account_id` string: Select another granted account for this request.
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `200`

Success

- object
  - `success` true, required
  - `data` object, required
    - `email` EmailSummary, required
      - `subject` string, nullable
      - `from_addresses` DecodedEmailAddress[]: Parsed From authors in header order, retaining multiple authors. Empty when absent/unparseable. Display names are not identity keys.
        - `address` string, required
        - `name` string, nullable, required
      - `to_addresses` DecodedEmailAddress[]: Parsed To recipients in header order, with named groups flattened. Empty when absent/unparseable; not trusted delivery routing.
        - `address` string, required
        - `name` string, nullable, required
      - `cc_addresses` DecodedEmailAddress[]: Parsed Cc recipients in header order, with named groups flattened. Empty when absent/unparseable.
        - `address` string, required
        - `name` string, nullable, required
      - `reply_to_addresses` DecodedEmailAddress[]: Parsed Reply-To addresses in header order. Empty when absent/unparseable. Does not authorize sending a reply.
        - `address` string, required
        - `name` string, nullable, required
      - `message_id` string, nullable: Sender Message-ID without angle brackets, preserving case. Null when absent/unparseable/ambiguous; never the Revdoku delivery ID.
      - `in_reply_to` string[]: Ordered parent Message-IDs without angle brackets, preserving case. Empty when absent/unparseable; multiple parents are retained.
      - `references` string[]: Ordered References IDs without angle brackets, preserving case. Empty when absent/unparseable.
      - `delivered_to` string
      - `received_at` string, date-time, required: Receipt time. For sent emails, the time Revdoku accepted the send.
      - `body_status` 'complete' | 'empty' | 'truncated' | 'unavailable' | 'withheld'
      - `omitted_attachment_count` integer
      - `id` string, required
      - `conversation_id` string, required: Email ID that identifies the conversation. Replies are linked by email headers. Filter a list with conversation_id.
      - `direction` 'received' | 'sent', required: received for incoming email; sent for email sent from this mailbox.
      - `delivery` EmailDelivery: Present on sent emails only.
        - `status` 'queued' | 'sending' | 'sent' | 'failed' | 'uncertain', required: uncertain: the provider result is unknown. Do not send again before you check the sent list.
        - `recipients` object, required: Status for each recipient address: queued, sent, delivered, bounced, bounced_temporarily, complained or rejected.
      - `labels` EmailLabel[], required: Labels on the email files. When AI labels are on for the account, they add one built-in category label, such as Junk or Receipts, a few seconds after the email arrives, usually after the email.received event.
        - `id` string, required
        - `name` string, required
        - `color` 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'gray', required
      - `withheld` boolean, required: True means Revdoku hides the email's content from API keys and MCP: the subject, display names, sender address (except its domain), body and attachments. If labels includes the Junk label, the email is junk: skip it. Downloads of the email and its files return EMAIL_WITHHELD, and a person can review it in the dashboard. Otherwise AI labels have not checked it yet: keep its ID and read it again with getEmail / get_email after a few seconds. The read returns 503 EMAIL_LABELING_PENDING with Retry-After until the label is ready (at most about one minute). Do not drop a pending email.
      - `file_id` string: Included only with include_storage=true for file-browser integration.
      - `version_id` string: Included only with include_storage=true for file-browser integration.
      - `attachment_count` integer, required
      - `read` boolean, required
      - `read_at` string, date-time, nullable, required
      - `read_by` object, nullable, required
      - `read_by_api_key` object, nullable, required
      - `files` object: Included only with include_storage=true for file-browser integration.
        - `body_id` string, nullable, required
        - `original_id` string, nullable, required
        - `attachment_ids` string[], required
        - `directory` string: Storage folder containing this email, without a trailing slash.
      - `forwarding` EmailForwarding: Server-recorded member forwarding provenance. The original author is reported by the member, not independently authenticated. Absent for ordinary or unrecognized mail.
        - `method` string, required
        - `member_id` string, required
        - `member_email` string, required
        - `intake_account_id` string, required
        - `outer_from` string
        - `outer_subject` string
        - `outer_message_id` string
        - `original_date_raw` string
        - `original_sent_at` string
        - `attribution` 'member_forwarded', required
        - `parser_version` integer, required: Parser implementation used at intake; does not change the forwarding response shape.

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

[API](https://skmtc.dev/revdoku/apis/revdoku-api.md) · [All operations](https://skmtc.dev/revdoku/apis/revdoku-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdoku/apis/revdoku-api/revisions/3ff4e2540a8b?raw)