---
title: "List conversations"
method: GET
path: "/v1/inboxes/{inbox_id}/threads"
tags: ["threads"]
---

# List conversations

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

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/inboxes/{inbox_id}/threads`
- Auth: HTTP bearer

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.

## Path parameters

- `inbox_id` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `query` string
- `from` string
- `recipient` string
- `subject` string
- `after` string
- `before` string
- `labels_all` Label[]
- `labels_any` Label[]
- `labels_none` Label[]
- `order` 'newest' | 'oldest' | 'relevance'

## Response `200`

Success.

- object
  - `threads` ThreadSummary[], required
    - `id` string, required: Cherami resource ID.
    - `inbox_id` string, required: Cherami resource ID.
    - `subject` string, nullable, required
    - `last_activity_at` string, date-time, required: UTC timestamp with milliseconds.
    - `message_count` integer, required
    - `received_count` integer, required
    - `accepted_count` integer, required
    - `rejected_count` integer, required
    - `unknown_count` integer, required
    - `latest_message` union, required: The conversation's newest message, whichever messages the filters matched. id is a received or sent message ID, according to direction.
      - object
        - `id` string, required: Cherami resource ID.
        - `direction` 'received', required
        - `counterpart` union, required: Mailbox or group from the message headers, written by the sender and not verified.
          - object
            - `name` string, required
            - `address` string, required
          - object
            - `name` string, required
            - `group` object[], required
              - …
        - `preview` Preview, required
          - `text` string, required: Start of the chosen text, whitespace collapsed; empty when the message added no new text.
          - `truncated` boolean, required: true when the chosen text was longer than the excerpt.
          - `source` 'reply_text' | 'text' | 'html', required: Which text the excerpt comes from.
      - object
        - `id` string, required: Cherami resource ID.
        - `direction` 'sent', required
        - `counterpart` Mailbox, required
          - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @.
          - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
        - `preview` Preview, required
          - `text` string, required: Start of the chosen text, whitespace collapsed; empty when the message added no new text.
          - `truncated` boolean, required: true when the chosen text was longer than the excerpt.
          - `source` 'reply_text' | 'text' | 'html', required: Which text the excerpt comes from.
    - `matching_message_ids` string[]
    - `matching_message_count` integer
  - `next_cursor` string, nullable, required: Cursor for the next page, or null at the end. Send it with the same URL, filters and order.

## Other responses

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

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)