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

# List messages

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

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/inboxes/{id}/messages`
- Auth: HTTP bearer

List all messages in an inbox, across every thread. Supports pagination for high-volume inboxes.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `offset` integer
- `direction` 'inbound' | 'outbound'

## Response `200`

List of messages

- object: List of messages
  - `data` Message[]
    - `id` string
    - `threadId` string
    - `direction` 'inbound' | 'outbound'
    - `fromAddr` string
    - `toAddr` string: Your OpenMail inbox address for inbound messages. For outbound sends, the primary recipient.
    - `headerTo` string, nullable: Inbound only. The address the sender wrote to (comma-separated if multiple). When deliveryRole is cc, reply to this address — not fromAddr.
    - `deliveryRole` 'to' | 'cc' | 'null', nullable: Inbound only. to if your inbox was the main recipient; cc if you were copied on the email.
    - `cc` string[]: Email addresses copied on the message.
    - `addressNames` object, nullable: Inbound only. Display names the sender's mail client put on From, To and Cc, keyed by lower-cased address, e.g. `{"alice@example.com": "Alice Smith"}`. Address fields stay bare so you can match on them. Null when the headers carried no names.
    - `bcc` string[]: Blind-copy recipients on outbound mail sent from this inbox. Empty on inbound. Not included in the copy delivered to To or Cc.
    - `subject` string
    - `bodyText` string
    - `bodyHtml` string
    - `attachments` object[]
      - `filename` string
      - `contentType` string
      - `sizeBytes` integer
      - `url` string: Signed URL for download
    - `rawUrl` string, nullable: URL of the original RFC 822 message (GET /v1/messages/{id}/raw). null when the bytes weren't kept.
    - `status` 'pending' | 'sent' | 'received' | 'failed'
    - `createdAt` string, date-time
  - `total` integer

## Other responses

- `401`: Missing, invalid, or expired API key
- `404`: Inbox not found

---

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