# Read a conversation

GET /v1/threads/{thread_id}

Source: https://cherami.to/docs/api/threads/get-thread



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

`GET /v1/threads/{thread_id}`

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

Returns the conversation's metadata and its messages, with bodies and attachment metadata. Each message has `direction` (`received` or `sent`), `timestamp`, and the fields of [received](https://cherami.to/docs/api/messages/get-message) or [sent](https://cherami.to/docs/api/sending/get-sent-message) detail.

The first page holds the newest messages, oldest first within the page; `next_cursor` fetches older ones. Order follows Cherami's receipt and send times, not the senders' Date headers. Counts describe the whole conversation.

Attachment bytes aren't included: [download](https://cherami.to/docs/api/messages/download-attachment) a received file, or read [sent detail](https://cherami.to/docs/api/sending/get-sent-message) for a sent file's base64 content.

Received messages that aren't ready, or failed, aren't part of a conversation; read them through the message endpoints.

## Parameters [#parameters]

| Parameter   | Location | Required | Type    | Meaning                                                                         |
| ----------- | -------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `thread_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. |

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/threads/THREAD_ID" \
  --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`.

[ThreadDetail](#schema-threaddetail)

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "subject": null,
  "last_activity_at": "2026-10-01T00:00:00.000Z",
  "message_count": 0,
  "received_count": 0,
  "accepted_count": 0,
  "rejected_count": 0,
  "unknown_count": 0,
  "messages": [],
  "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.

* `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)

### HTTP 503 [#http-503]

`content_unavailable`: Stored content could not be read. Retry later.

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

Content type: `application/json`.

[Error](#schema-error)

## Schema: ThreadDetail [#schema-threaddetail]

| 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`                                                                                                    |
| `messages`         | Yes      | array of [ThreadReceivedDetail](#schema-threadreceiveddetail) or [ThreadSentDetail](#schema-threadsentdetail) |                                                                                                                   |
| `next_cursor`      | Yes      | string or null                                                                                                |                                                                                                                   |

## Schema: ThreadReceivedDetail [#schema-threadreceiveddetail]

All of these schemas apply.

### Part 1 [#part-1]

[ReceivedDetail](#schema-receiveddetail)

### Part 2 [#part-2]

| Field       | Required | Type         | Meaning and constraints                                                                                           |
| ----------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `direction` | Yes      | `"received"` |                                                                                                                   |
| `timestamp` | 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$` |

## Schema: ReceivedDetail [#schema-receiveddetail]

Exactly one of these shapes applies.

### Alternative 1 [#alternative-1]

| Field               | Required | Type                                       | Meaning and constraints                                                                                           |
| ------------------- | -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `id`                | Yes      | string                                     | Cherami resource ID.                                                                                              |
| `inbox_id`          | Yes      | string                                     | Cherami resource ID.                                                                                              |
| `thread_id`         | Yes      | string or null                             |                                                                                                                   |
| `envelope_from`     | Yes      | string                                     |                                                                                                                   |
| `envelope_to`       | Yes      | string                                     |                                                                                                                   |
| `subject`           | Yes      | string or null                             |                                                                                                                   |
| `received_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$` |
| `processing_status` | Yes      | `"ready"`                                  |                                                                                                                   |
| `labels`            | Yes      | array of string                            |                                                                                                                   |
| `message_id`        | Yes      | string or null                             | The message's Message-ID header, not a Cherami ID: reply and forward take id.                                     |
| `raw_size`          | Yes      | integer                                    | `minimum`: `0`                                                                                                    |
| `processed_at`      | Yes      | string or null                             |                                                                                                                   |
| `content`           | Yes      | [ReceivedContent](#schema-receivedcontent) |                                                                                                                   |

### Alternative 2 [#alternative-2]

| Field               | Required | Type                                        | Meaning and constraints                                                                                           |
| ------------------- | -------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `inbox_id`          | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `thread_id`         | Yes      | string or null                              |                                                                                                                   |
| `envelope_from`     | Yes      | string                                      |                                                                                                                   |
| `envelope_to`       | Yes      | string                                      |                                                                                                                   |
| `subject`           | Yes      | string or null                              |                                                                                                                   |
| `received_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$` |
| `processing_status` | Yes      | `"pending"` or `"processing"` or `"failed"` |                                                                                                                   |
| `labels`            | Yes      | array of string                             |                                                                                                                   |
| `message_id`        | Yes      | string or null                              | The message's Message-ID header, not a Cherami ID: reply and forward take id.                                     |
| `raw_size`          | Yes      | integer                                     | `minimum`: `0`                                                                                                    |
| `processed_at`      | Yes      | string or null                              |                                                                                                                   |

## Schema: ReceivedContent [#schema-receivedcontent]

| Field         | Required | Type                                                      | Meaning and constraints                                                                            |
| ------------- | -------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `from`        | Yes      | [ParsedAddress](#schema-parsedaddress) or null            |                                                                                                    |
| `sender`      | Yes      | [ParsedAddress](#schema-parsedaddress) or null            |                                                                                                    |
| `reply_to`    | Yes      | array of [ParsedAddress](#schema-parsedaddress)           |                                                                                                    |
| `to`          | Yes      | array of [ParsedAddress](#schema-parsedaddress)           |                                                                                                    |
| `cc`          | Yes      | array of [ParsedAddress](#schema-parsedaddress)           |                                                                                                    |
| `bcc`         | Yes      | array of [ParsedAddress](#schema-parsedaddress)           |                                                                                                    |
| `subject`     | Yes      | string or null                                            |                                                                                                    |
| `message_id`  | Yes      | string or null                                            | Message-ID header as the sender wrote it.                                                          |
| `in_reply_to` | Yes      | string or null                                            |                                                                                                    |
| `references`  | Yes      | string or null                                            |                                                                                                    |
| `date`        | Yes      | string or null                                            | The sender's Date header: ISO when it parses, otherwise as written. Use received\_at for ordering. |
| `reply_text`  | Yes      | string or null                                            | New text without quoted history. Empty: there is none. Null: it couldn't be extracted.             |
| `text`        | Yes      | string or null                                            |                                                                                                    |
| `html`        | Yes      | string or null                                            |                                                                                                    |
| `attachments` | Yes      | array of [ReceivedAttachment](#schema-receivedattachment) |                                                                                                    |

## 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: ReceivedAttachment [#schema-receivedattachment]

| Field         | Required | Type           | Meaning and constraints |
| ------------- | -------- | -------------- | ----------------------- |
| `id`          | Yes      | string         |                         |
| `filename`    | Yes      | string or null |                         |
| `size`        | Yes      | integer        | `minimum`: `0`          |
| `mime_type`   | Yes      | string         |                         |
| `disposition` | Yes      | string or null |                         |
| `content_id`  | Yes      | string or null |                         |
| `related`     | Yes      | boolean        |                         |

## Schema: ThreadSentDetail [#schema-threadsentdetail]

| Field                 | Required | Type                                        | Meaning and constraints                                                                                           |
| --------------------- | -------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                  | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `inbox_id`            | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `created_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$` |
| `recipient_count`     | Yes      | integer                                     | `minimum`: `0`                                                                                                    |
| `status`              | Yes      | `"accepted"` or `"rejected"` or `"unknown"` |                                                                                                                   |
| `provider_message_id` | Yes      | string or null                              | Message-ID the provider assigned when it accepted the message.                                                    |
| `error_code`          | Yes      | string or null                              | Reason code for a rejected or unknown outcome, such as E\_RECIPIENT\_SUPPRESSED or acceptance\_unknown.           |
| `thread_id`           | Yes      | string or null                              |                                                                                                                   |
| `in_reply_to`         | Yes      | string or null                              |                                                                                                                   |
| `labels`              | Yes      | array of string                             |                                                                                                                   |
| `direction`           | Yes      | `"sent"`                                    |                                                                                                                   |
| `timestamp`           | 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$` |
| `reply_text`          | Yes      | string or null                              | New text without quoted history. Empty: there is none. Null: it couldn't be extracted; read submission.           |
| `submission`          | Yes      | object                                      |                                                                                                                   |

### `submission` fields [#submission-fields]

| Field         | Required | Type                                          | Meaning and constraints |
| ------------- | -------- | --------------------------------------------- | ----------------------- |
| `to`          | Yes      | array of [Mailbox](#schema-mailbox) or string |                         |
| `cc`          | Yes      | array of [Mailbox](#schema-mailbox) or string |                         |
| `bcc`         | Yes      | array of [Mailbox](#schema-mailbox) or string |                         |
| `subject`     | Yes      | string                                        |                         |
| `text`        | Yes      | string                                        |                         |
| `html`        | No       | string                                        |                         |
| `attachments` | Yes      | array of object                               |                         |
| `from`        | Yes      | [Mailbox](#schema-mailbox) or string          |                         |
| `headers`     | No       | object                                        |                         |

#### `attachments` fields [#attachments-fields]

| Field       | Required | Type    | Meaning and constraints |
| ----------- | -------- | ------- | ----------------------- |
| `id`        | Yes      | string  |                         |
| `filename`  | Yes      | string  |                         |
| `mime_type` | Yes      | string  |                         |
| `size`      | Yes      | integer | `minimum`: `0`          |

#### `headers` fields [#headers-fields]

| Field         | Required | Type   | Meaning and constraints |
| ------------- | -------- | ------ | ----------------------- |
| `In-Reply-To` | Yes      | string |                         |
| `References`  | Yes      | string |                         |

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