---
title: "Read a received message"
method: GET
path: "/v1/messages/{message_id}"
tags: ["messages"]
---

# Read a received message

`GET /v1/messages/{message_id}`

## Request

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

Returns one received message. Check `processing_status` first:

- `ready`: `content` holds the parsed headers, the text and HTML bodies, `reply_text` and attachment metadata. The sender is `content.from`.
- `pending` or `processing`: the content isn't ready yet; read the message again shortly.
- `failed`: the content couldn't be prepared. The [raw MIME](https://cherami.to/docs/api/messages/download-raw-message) is still available.

For answers written between quoted lines, read `text` or `html` rather than `reply_text`.

Download an attachment by its `id` in `content.attachments`, with the [attachment endpoint](https://cherami.to/docs/api/messages/download-attachment).

## Path parameters

- `message_id` string, required

## Response `200`

Success.

- 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
    - `message_id` string, nullable, required: The message's Message-ID header, not a Cherami ID: reply and forward take id.
    - `raw_size` integer, required
    - `processed_at` string, date-time, nullable, required: UTC timestamp with milliseconds.
    - `content` ReceivedContent, required
      - `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
            - `name` string, required
            - `address` string, required
      - `sender` 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
            - `name` string, required
            - `address` string, required
      - `reply_to` ParsedAddress[], required
        - union: 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
              - …
      - `to` ParsedAddress[], required
        - union: 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
              - …
      - `cc` ParsedAddress[], required
        - union: 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
              - …
      - `bcc` ParsedAddress[], required
        - union: 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
              - …
      - `subject` string, nullable, required
      - `message_id` string, nullable, required: Message-ID header as the sender wrote it.
      - `in_reply_to` string, nullable, required
      - `references` string, nullable, required
      - `date` string, nullable, required: The sender's Date header: ISO when it parses, otherwise as written. Use received_at for ordering.
      - `reply_text` string, nullable, required: New text without quoted history. Empty: there is none. Null: it couldn't be extracted.
      - `text` string, nullable, required
      - `html` string, nullable, required
      - `attachments` ReceivedAttachment[], required
        - `id` string, required
        - `filename` string, nullable, required
        - `size` integer, required
        - `mime_type` string, required
        - `disposition` string, nullable, required
        - `content_id` string, nullable, required
        - `related` boolean, 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
    - `message_id` string, nullable, required: The message's Message-ID header, not a Cherami ID: reply and forward take id.
    - `raw_size` integer, required
    - `processed_at` string, date-time, nullable, required: UTC timestamp with milliseconds.

## Other responses

- `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.
- `503`: `content_unavailable`: Stored content could not be read. Retry later.

---

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