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

# List received messages

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

## Request

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

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

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.

## 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
  - `messages` ReceivedSummary[], required
    - union
      - object
        - `id` string, required: Cherami resource ID.
        - `inbox_id` string, required: Cherami resource ID.
        - `thread_id` string, nullable, required: Cherami resource ID.
        - `envelope_from` string, required
        - `envelope_to` string, required
        - `subject` string, nullable, required
        - `received_at` string, date-time, required: UTC timestamp with milliseconds.
        - `processing_status` 'ready', required
        - `labels` string[], 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.
        - `from` 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
              - …
      - object
        - `id` string, required: Cherami resource ID.
        - `inbox_id` string, required: Cherami resource ID.
        - `thread_id` string, nullable, required: Cherami resource ID.
        - `envelope_from` string, required
        - `envelope_to` string, required
        - `subject` string, nullable, required
        - `received_at` string, date-time, required: UTC timestamp with milliseconds.
        - `processing_status` 'pending' | 'processing' | 'failed', required
        - `labels` string[], required
        - `preview` unknown, required
  - `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)