# Messages

List a mailbox's messages and read one back as structured content.

Messages live inside a mailbox. Listing them gives you metadata and a snippet;
reading one gives you decoded headers, bodies, and attachment references.

Paths are relative to `https://api.open.email/api/v1`, and every request carries
a bearer credential — see [Authentication](/docs/guides/authentication).

## List messages

[`GET /mailboxes/{mailboxId}/messages`](/docs/api/messages/get_MessageList)

```bash
curl "$API/mailboxes/$MAILBOX_ID/messages?limit=25" \
  -H "Authorization: Bearer $TOKEN"
```

Newest first by default, with cursor pagination. You can restrict to one label,
filter on flags, and switch `state` to `expunged` to list the trash instead.

**Hold `order` constant across a crawl.** Cursors do not encode direction, so
reusing one under the opposite order silently yields a differently-windowed
page rather than an error.

```json
{
  "messages": [
    {
      "id": "msg_...",
      "subject": "Hello from OpenEmail",
      "snippet": "Sent over HTTP.",
      "labels": [{ "name": "INBOX", "uid": 1, "uidValidity": 1 }],
      "receivedAt": 1786000000,
      "threadId": "thr_...",
      "uid": 1
    }
  ],
  "nextCursor": "..."
}
```

`receivedAt` and `sentAt` are Unix timestamps. Each entry in `labels` carries
its own `uid` — labels are how OpenEmail models folders, and IMAP requires a
per-folder UID.

## Read a message

[`GET /mailboxes/{mailboxId}/messages/{messageId}/content`](/docs/api/messages/get_MessageGetContent)

```bash
curl "$API/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID/content" \
  -H "Authorization: Bearer $TOKEN"
```

Returns the message decoded and structured — you do not have to parse MIME
yourself:

```json
{
  "headers": {
    "from": [{ "email": "you@example.com", "name": null }],
    "subject": "Hello from OpenEmail",
    "date": 1786000000
  },
  "text": "Sent over HTTP.",
  "html": null,
  "attachments": []
}
```

Attachments come back as references, not bytes. Each carries a `section` — the
MIME part identifier you pass to the message parts endpoint to stream it — plus
the filename, content type and size the sender declared. One field is easy to
miss: `degraded` marks a part whose metadata could not be read in full, so
treat its filename and size as unreliable rather than absent.

Two failures are **terminal for a given message**, and worth handling as such
rather than retrying: `413 message_too_large` when the blob exceeds the parse
ceiling, and `422 unparseable_message` or `message_too_complex`. The content
endpoint will not succeed on a later attempt for either. Fall back to streaming
the raw MIME blob instead.

The endpoint also honours `If-None-Match` against the content ETag, so a poller
can take a `304` instead of the body.

## In the TypeScript SDK

Each call above is a method of the [TypeScript SDK](/docs/sdks/typescript):

- [`messages.list`](/docs/sdks/typescript/messages/list) is
  `GET /mailboxes/{mailboxId}/messages`; iterated with `for await`, it is
  every message of every page ([Listings](/docs/sdks/typescript/listings)).
- [`messages.getContent`](/docs/sdks/typescript/messages/get-content) is
  `GET /mailboxes/{mailboxId}/messages/{messageId}/content`, and its
  `ifNoneMatch` option takes the content's ETag
  ([conditional reads](/docs/sdks/typescript/responses#conditional-reads)).
