---
title: "List emails"
method: GET
path: "/v1/mailboxes/{mailbox_id}/emails"
tags: ["Emails"]
---

# List emails

`GET /v1/mailboxes/{mailbox_id}/emails`

## Request

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

Requires mailbox read permission. Lists received email by default. To poll, list in ascending order, save pagination.next_cursor after every page (including an empty page) and send it next time with the same filters. Listing never marks email read.

## Path parameters

- `mailbox_id` string, required

## Query parameters

- `account_id` string
- `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.
- `limit` integer
- `cursor` string
- `order` 'asc' | 'desc'
- `direction` 'received' | 'sent' | 'all'
- `sender` string
- `subject` string
- `received_after` string, date-time
- `received_before` string, date-time
- `read` boolean
- `has_attachments` boolean
- `conversation_id` string
- `include_storage` boolean

## Response `200`

Success

- object
  - `success` true, required
  - `data` EmailList, required
    - `emails` 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.
    - `pagination` Pagination, required: One page of a list. Request the next page with cursor=next_cursor and the same filters. Cursors are opaque strings: do not build or decode them.
      - `limit` integer, required
      - `has_more` boolean, required: True when another page exists.
      - `next_cursor` string, nullable, required: Cursor for the next page; null on the last page. Email lists always return a cursor so that you can poll for new mail.

## 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)