# List conversation threads

Returns conversation threads, newest activity first, one row per conversation: participants, message and unread counts, and an exemplar message carrying the subject and snippet a row renders. Grouping is by REPLY CHAIN (In-Reply-To/References), never by subject — two unrelated messages sharing a subject are two conversations, and a renamed reply stays in the one it answers. Filtering by `label` and by unread/starred flags uses Gmail semantics: a conversation matches when ANY of its live members does, and the counts then span the whole conversation — but the exemplar is the newest member that MATCHED, so a label-filtered row is faced with the message that folder actually holds. See ThreadListItem.exemplar. Trash and Junk are HIDDEN ROLES: outside their own views a conversation is its live members carrying neither label — they do not qualify a row, are not counted, faced or listed in `participants`/`labels`. `label=Trash` lists conversations by their trashed members and `label=Junk` by their junked ones; a member in both is in the bin (shown in Trash, hidden in Junk). `excludeRoles` adds to that rule and never lifts it.

## `GET /api/v1/mailboxes/{mailboxId}/threads`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `label` (string) — Filter threads containing messages with this label (e.g. INBOX)
- `excludeRoles` ("inbox" | "sent" | "drafts" | "trash" | "archive" | "junk"[]) — System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.
- `cursor` (string) — Pagination cursor from previous page
- `limit` (integer, ≥ 1, ≤ 100) — Maximum threads to return per page (max 100)
- `order` ("asc" | "desc") — Listing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring
- `sortBy` ("arrival" | "date") — Sort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header
- `hasFlags` (string) — Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)
- `notFlags` (string) — Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)

### Responses

**200** — List of conversation threads

`application/json` → object

- `threads` (ThreadListItem[], required)
  - `exemplar` (MessageMeta & object, required)
    - `auth` (MessageAuth, required) — Stored SMTP authentication and original inbound junk verdicts. Missing verdicts are null; the object is null when none were recorded (including APPEND and local Sent copies). Junk does not follow later label changes.
      - `arc` (string | null, required) — ARC verdict, or null
      - `dkim` (string | null, required) — DKIM verdict, or null
      - `dmarc` (string | null, required) — DMARC verdict, or null
      - `junk` (boolean | null, required) — The inbound spam verdict (X-OpenEmail-Junk), or null when none was stamped
      - `spf` (string | null, required) — SPF verdict (pass/fail/softfail/none/...), or null
    - `bcc` (array | null, required) — Parsed Bcc header addresses for composed drafts, or null
    - `blobGen` (string, required) — Storage generation identifier
    - `blobHash` (string, required) — SHA-256 hash of raw MIME content in storage
    - `cc` (array | null, required) — Parsed Cc header addresses, or null if unparseable
    - `deliveryMeta` (object | null, required) — Inbound delivery audit metadata
    - `deliveryState` ("queued" | "relayed" | "delivered" | "failed" | "mixed" | null, required) — What became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery.
      - _option 1: "queued" | "relayed" | "delivered" | "failed" | "mixed"_
      - _option 2: null_
      - _option 3: null_
    - `envelopeFrom` (string, required) — SMTP envelope sender address
    - `envelopeTo` (string, required) — SMTP envelope recipient address
    - `flags` (string[], required) — System flags (seen, answered, flagged, draft, deleted)
    - `from` (array | null, required) — Parsed From header addresses, or null if unparseable
    - `hasAttachment` (boolean | null, required) — True if message has file attachments, null if not yet determined
    - `id` (string, required) — Unique message identifier (ULID)
    - `inReplyTo` (string | null, required) — In-Reply-To header Message-ID, or null
    - `keywords` (string[], required) — Custom JMAP keywords (e.g. $forwarded)
    - `labels` (MessageLabel[], required) — Labels attached to this message with per-label UIDs
      - `deleted` (boolean, required) — This membership's IMAP \Deleted mark (set with `flagLabel` on PATCH, acted on by POST /labels/{label}/expunge). Always present; false when unmarked. Per label, so the same message can be marked in one folder and clean in another
      - `modseq` (integer <int64>, required) — RFC 7162 MODSEQ change sequence number
      - `name` (string, required) — Label name
      - `uid` (integer <int64>, required) — Message UID inside this label
      - `uidValidity` (integer <int64>, required) — UID validity epoch of the label
    - `messageIdHeader` (string | null, required) — Message-ID header value, or null
    - `receivedAt` (integer <int64>, required) — Timestamp when message was received by server in epoch seconds
    - `referencesIds` (string[], required) — List of Message-IDs from References header
    - `sentAt` (integer | null, required) — Sent timestamp from Date header in epoch seconds, or null
    - `size` (integer <int64>, required) — Total message size in bytes
    - `snippet` (string | null, required) — Short plain-text preview of message body
    - `subject` (string | null, required) — Message subject line, or null
    - `threadId` (string | null, required) — Conversation thread identifier (ULID), or null
    - `to` (array | null, required) — Parsed To header addresses, or null if unparseable
    - `modseq` (integer <int64>) — Per-label MODSEQ (present in label UID listings)
    - `restoresTo` (array | null) — Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.
    - `uid` (integer <int64>) — Per-label UID (present in label UID listings)
  - `flaggedCount` (integer <int64>, required) — Flagged (starred) live messages in this conversation, over the same population as messageCount. Read this and not exemplar's `flagged` flag to decide whether a row shows a star: a star on any other member is otherwise invisible from the list, and so cannot be cleared from it. To clear them all, PATCH /messages with `threadIds` and `flagsClear: ["flagged"]`. Not viewer-relative, unlike unseenCount: only `seen` is a per-viewer overlay.
  - `labels` (string[], required) — Distinct label names across this conversation's live members, ordered by sort_order then name. Excludes the members the row excludes: those in Trash or Junk outside their own views, and those carrying an excludeRoles role. Limited to the viewer's granted labels.
  - `lastReceivedAt` (integer <int64>, required) — When this conversation last had activity, in epoch seconds — the newest live member's arrival, ANYWHERE in the thread, which is also what the listing sorts by. May be newer than exemplar.receivedAt: the position is conversation-wide, the exemplar is folder-relative (see exemplar).
  - `messageCount` (integer <int64>, required) — Live messages in this conversation, across every label — not just the one filtered by. Matches what GET /threads/{threadId} returns, so a row's count agrees with the conversation a client then renders.
  - `participants` (ThreadParticipant[], required) — Distinct senders in the conversation, oldest first, deduplicated by address — the "Carol, Alice, Bob" line a conversation row shows, which the exemplar alone cannot supply. Conversation-wide like messageCount, so an Inbox row for a thread you replied to lists you as well. Bounded and capped at 8 entries: read from the conversation's opener plus its 20 newest live members, so a long thread reports who started it and who is still in it, and elides the middle. Scoped and filtered like the rest of the row (Trash and Junk members hidden outside their own views), so the Trash view of a conversation lists the people in its trashed half.
    - `email` (string, required) — Email address
    - `name` (string | null, required) — Display name or personal name, or null
  - `threadId` (string, required) — Conversation thread ULID identifier
  - `unseenCount` (integer <int64>, required) — Unread live messages in this conversation, over the same population as messageCount. Read this and not exemplar's `seen` flag to decide whether a row is unread: the exemplar is one member and may be read while older ones are not.
- `nextCursor` (string) — Opaque cursor for the next page; absent on the last page

**400** — validation_failed — invalid query parameters or mismatched cursor

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or label not found

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/threads' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.threads.list`](/docs/sdks/typescript/threads/list)

```ts
for await (const threadListItem of openemail.threads.list(mailboxId)) {
  // every item of every page (await the call instead for one page)
}
```
