# List conversations

GET /v1/inboxes/{inbox_id}/threads

Source: https://cherami.to/docs/api/threads/list-threads



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`GET /v1/inboxes/{inbox_id}/threads`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Lists the inbox's conversations, most recent activity first. A conversation holds ready received messages and every send attempt, `rejected` and `unknown` included, and its counts include them.

The [search, filters and ordering](https://cherami.to/docs/guides/search) of message listings apply; a conversation matches when one of its messages meets every condition. Filtered results add `matching_message_ids` (up to 100, newest first) and `matching_message_count`.

`subject` is the earliest message's. `latest_message` is the newest message, whichever messages matched: its `id`, `direction`, `counterpart` (the From of received mail, or the first To of sent mail) and [`preview`](https://cherami.to/docs/api/messages/list-messages#previews).

Labels belong to messages, not conversations. Reply using a message's `id`, not the thread ID.

## Parameters [#parameters]

| Parameter     | Location | Required | Type                                      | Meaning                                                                                                                                                                                                                                                                                 |
| ------------- | -------- | -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inbox_id`    | path     | Yes      | string                                    | Cherami resource ID returned by the API.                                                                                                                                                                                                                                                |
| `limit`       | query    | No       | integer                                   | Results per page. `minimum`: `1` `maximum`: `100` `default`: `20`                                                                                                                                                                                                                       |
| `cursor`      | query    | No       | string                                    | next\_cursor from the previous page. Keep the URL, filters and order unchanged.                                                                                                                                                                                                         |
| `query`       | query    | No       | string                                    | Words or "quoted phrases" to find in the subject and body; every term must match. At most 16 terms and 512 UTF-16 code units. OR, NOT and wildcards have no special meaning, and attachments aren't searched. See [Find mail](https://cherami.to/docs/guides/search).                                     |
| `from`        | query    | No       | string                                    | Bare sender address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.                                                                                                                                             |
| `recipient`   | query    | No       | string                                    | Bare recipient address from the message headers, matched exactly without regard to case; not the SMTP envelope. At most 320 UTF-16 code units.                                                                                                                                          |
| `subject`     | query    | No       | string                                    | Text the subject contains, matched literally without regard to case. At most 998 UTF-16 code units.                                                                                                                                                                                     |
| `after`       | query    | No       | string                                    | Earliest (inclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z\|[+-]\d{2}:\d{2})$` |
| `before`      | query    | No       | string                                    | Latest (exclusive) receipt or send time, as an ISO 8601 instant with a timezone, such as 2026-10-01T00:00:00Z. after must be earlier than before. URL-encode it, including any + in an offset. `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z\|[+-]\d{2}:\d{2})$`   |
| `labels_all`  | query    | No       | array of [Label](#schema-label)           | Messages carrying every listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. `maxItems`: `32`                                                                                                                 |
| `labels_any`  | query    | No       | array of [Label](#schema-label)           | Messages carrying at least one listed label. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. `maxItems`: `32`                                                                                                          |
| `labels_none` | query    | No       | array of [Label](#schema-label)           | Messages carrying none of the listed labels, unlabeled ones included. Repeat the parameter for each label rather than separating with commas. The three label groups combine with AND. `maxItems`: `32`                                                                                 |
| `order`       | query    | No       | `"newest"` or `"oldest"` or `"relevance"` | relevance requires query. `default`: `newest`                                                                                                                                                                                                                                           |

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/threads" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Success.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

| Field         | Required | Type                                            | Meaning and constraints |
| ------------- | -------- | ----------------------------------------------- | ----------------------- |
| `threads`     | Yes      | array of [ThreadSummary](#schema-threadsummary) |                         |
| `next_cursor` | Yes      | string or null                                  |                         |

```json
{
  "threads": [],
  "next_cursor": null
}
```

### HTTP 400 [#http-400]

`invalid_limit`: Use an integer from 1 to 100.

`invalid_cursor`: Send a cursor only to the listing, filters and order that returned it, or restart from the first page.

`invalid_search`: Correct the search terms, filters, timestamps or ordering the message names. See [search](https://cherami.to/docs/guides/search).

`invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: Label [#schema-label]

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. `x-max-utf8-bytes`: `128`

## Schema: ThreadSummary [#schema-threadsummary]

| Field                    | Required | Type                                               | Meaning and constraints                                                                                           |
| ------------------------ | -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                     | Yes      | string                                             | Cherami resource ID.                                                                                              |
| `inbox_id`               | Yes      | string                                             | Cherami resource ID.                                                                                              |
| `subject`                | Yes      | string or null                                     |                                                                                                                   |
| `last_activity_at`       | Yes      | string                                             | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |
| `message_count`          | Yes      | integer                                            | `minimum`: `0`                                                                                                    |
| `received_count`         | Yes      | integer                                            | `minimum`: `0`                                                                                                    |
| `accepted_count`         | Yes      | integer                                            | `minimum`: `0`                                                                                                    |
| `rejected_count`         | Yes      | integer                                            | `minimum`: `0`                                                                                                    |
| `unknown_count`          | Yes      | integer                                            | `minimum`: `0`                                                                                                    |
| `latest_message`         | Yes      | [ThreadLatestMessage](#schema-threadlatestmessage) |                                                                                                                   |
| `matching_message_ids`   | No       | array of string                                    | `maxItems`: `100`                                                                                                 |
| `matching_message_count` | No       | integer                                            | `minimum`: `0`                                                                                                    |

## Schema: ThreadLatestMessage [#schema-threadlatestmessage]

The conversation's newest message, whichever messages the filters matched. id is a received or sent message ID, according to direction.

Exactly one of these shapes applies.

### Alternative 1 [#alternative-1]

| Field         | Required | Type                                           | Meaning and constraints               |
| ------------- | -------- | ---------------------------------------------- | ------------------------------------- |
| `id`          | Yes      | string                                         | Cherami resource ID.                  |
| `direction`   | Yes      | `"received"`                                   |                                       |
| `counterpart` | Yes      | [ParsedAddress](#schema-parsedaddress) or null | The message's From; null when absent. |
| `preview`     | Yes      | [Preview](#schema-preview) or null             |                                       |

### Alternative 2 [#alternative-2]

| Field         | Required | Type                               | Meaning and constraints                                                                                            |
| ------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`          | Yes      | string                             | Cherami resource ID.                                                                                               |
| `direction`   | Yes      | `"sent"`                           |                                                                                                                    |
| `counterpart` | Yes      | [Mailbox](#schema-mailbox) or null | First To recipient, as a lowercase address without a name; null when unavailable. Sent detail has every recipient. |
| `preview`     | Yes      | [Preview](#schema-preview) or null |                                                                                                                    |

## Schema: ParsedAddress [#schema-parsedaddress]

Mailbox or group from the message headers, written by the sender and not verified.

Exactly one of these shapes applies.

### Alternative 1 [#alternative-1-1]

| Field     | Required | Type   | Meaning and constraints |
| --------- | -------- | ------ | ----------------------- |
| `name`    | Yes      | string |                         |
| `address` | Yes      | string |                         |

### Alternative 2 [#alternative-2-1]

| Field   | Required | Type            | Meaning and constraints |
| ------- | -------- | --------------- | ----------------------- |
| `name`  | Yes      | string          |                         |
| `group` | Yes      | array of object |                         |

#### `group` fields [#group-fields]

| Field     | Required | Type   | Meaning and constraints |
| --------- | -------- | ------ | ----------------------- |
| `name`    | Yes      | string |                         |
| `address` | Yes      | string |                         |

## Schema: Preview [#schema-preview]

| Field       | Required | Type                                   | Meaning and constraints                                                                                      |
| ----------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `text`      | Yes      | string                                 | Start of the chosen text, whitespace collapsed; empty when the message added no new text. `maxLength`: `300` |
| `truncated` | Yes      | boolean                                | true when the chosen text was longer than the excerpt.                                                       |
| `source`    | Yes      | `"reply_text"` or `"text"` or `"html"` | Which text the excerpt comes from.                                                                           |

## Schema: Mailbox [#schema-mailbox]

| Field     | Required | Type   | Meaning and constraints                                                                                                                 |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | Yes      | string | Bare address such as [alex@example.com](mailto:alex@example.com): ASCII, at most 254 characters and 64 before the @. `maxLength`: `254` |
| `name`    | No       | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. `x-max-utf8-bytes`: `256`          |

Unknown fields are rejected.

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
