---
title: "GET /v1/mailboxes/{mailboxId}/threads"
method: GET
path: "/v1/mailboxes/{mailboxId}/threads"
---

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

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

## Request

- The document declares no server URL.
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `/authorize`, token URL `/oauth/token`, scopes: `email.read`)
  - HTTP bearer

One mailbox's threads, most recently active first, narrowed by the filter. `limit` defaults to 50.

## Path parameters

- `mailboxId` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `archived` boolean
- `trashed` boolean
- `outbound` boolean
- `unread` boolean
- `q` SearchTerm[]
- `from` string: One search term — a word or a phrase. Its words (runs of letters and digits, case aside, and accents aside on Latin letters) must appear in order in one field of one message, every word whole but the last, which may be the start of a word: `annual pl` finds "the Annual Plan". A term with no letter or digit in it is passed over beside terms that have one; alone, or as the value of `from`, `to` or `subject`, it matches nothing.
- `to` string: One search term — a word or a phrase. Its words (runs of letters and digits, case aside, and accents aside on Latin letters) must appear in order in one field of one message, every word whole but the last, which may be the start of a word: `annual pl` finds "the Annual Plan". A term with no letter or digit in it is passed over beside terms that have one; alone, or as the value of `from`, `to` or `subject`, it matches nothing.
- `subject` string: One search term — a word or a phrase. Its words (runs of letters and digits, case aside, and accents aside on Latin letters) must appear in order in one field of one message, every word whole but the last, which may be the start of a word: `annual pl` finds "the Annual Plan". A term with no letter or digit in it is passed over beside terms that have one; alone, or as the value of `from`, `to` or `subject`, it matches nothing.
- `hasAttachment` boolean
- `before` string, date-time
- `after` string, date-time
- `thread` string

## Response `200`

The request has succeeded.

- object: `{ data, nextCursor }` — the one envelope every paged collection answers with. The cursor is opaque and ours to change; a caller must never construct one. **`nextCursor` is non-null exactly when the page came back full** — so a full final page hands out a cursor whose next page is empty, which is correct and cheaper than over-fetching by one row to find out. A cursor the server cannot read answers 400 rather than silently restarting: a client looping "fetch, follow nextCursor" against a cursor that quietly reset would loop over page one forever.
  - `data` Thread[], required
    - `mailboxId` string, required: The mailbox this row lives in. Redundant on a per-mailbox read; load-bearing on the union read.
    - `id` string, required
    - `subject` string, required: The subject of the message that started the thread — a `Re:` never retitles it.
    - `from` string, required: The counterparty for the list row: a display name if one was stored, else the address. A broadcast's Sent copy is named for its audience.
    - `fromAddress` string, required: The counterparty's bare address — never a display name. On a broadcast's Sent copy it is the empty group the copy was addressed to (see `Message.to`), which names nobody to write to.
    - `snippet` string, required: One-line preview of the newest message's body.
    - `lastMessageAt` string, date-time, required
    - `messageCount` integer, required
    - `unread` boolean, required: Per-mailbox triage flags. An untouched thread is unread iff it has inbound mail.
    - `archived` boolean, required
    - `trashed` boolean, required: In the Trash. Only the Trash view (`trashed=true`) lists one; it is erased for good 30 days after it went in, or sooner by `deleteThread` / `emptyTrash`.
    - `hasOutbound` boolean, required: Whether this mailbox has sent anything on the thread — "we replied".
  - `nextCursor` string, nullable, required: Opaque. Non-null exactly when this page was full; `null` otherwise.

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/mailbox.md) - [All operations](https://skmtc.dev/foundermail/apis/mailbox/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/mailbox/revisions/6a50628a86ed?raw)