# List received messages

GET /v1/inboxes/{inbox_id}/messages

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



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

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

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

Lists received mail in the inbox, newest first. Narrow it with `query` and the sender, recipient, subject, date and label filters, or order by `oldest` or `relevance`: see [Find mail](https://cherami.to/docs/guides/search) and [labels](https://cherami.to/docs/guides/labels). Follow `next_cursor` with the same filters and order for the next page ([pagination](https://cherami.to/docs/api/errors#pagination)).

A message is listed as soon as it arrives. Only entries with `processing_status: "ready"` have `from` and a `preview`, and `thread_id` stays null until then. Identify the sender by `from`, a parsed mailbox such as `{"name":"Sender","address":"sender@example.com"}` or a group such as `{"name":"Team","group":[...]}`; `envelope_from` is the SMTP sender and can be a bounce address.

### Previews [#previews]

Received and sent listings include `preview`, an excerpt of up to 300 characters, null until the message's content is ready. It starts from the new reply text when that can be extracted, so even an untruncated preview can leave out the rest of the body: [read the message](https://cherami.to/docs/api/messages/get-message) before acting on it.

## 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/messages" \
  --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 |
| ------------- | -------- | --------------------------------------------------- | ----------------------- |
| `messages`    | Yes      | array of [ReceivedSummary](#schema-receivedsummary) |                         |
| `next_cursor` | Yes      | string or null                                      |                         |

```json
{
  "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.

`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: ReceivedSummary [#schema-receivedsummary]

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                                |                                                                                                                   |
| `preview`           | Yes      | [Preview](#schema-preview) or null             |                                                                                                                   |
| `from`              | Yes      | [ParsedAddress](#schema-parsedaddress) or null |                                                                                                                   |

### 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                             |                                                                                                                   |
| `preview`           | Yes      | null                                        |                                                                                                                   |

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