---
title: "List messages (one row per thread) for a mailbox"
method: GET
path: "/v1/messages"
tags: ["Messages"]
---

# List messages (one row per thread) for a mailbox

`GET /v1/messages`

## Request

- Base URL: `https://api.usemektup.com`
- URL: `https://api.usemektup.com/v1/messages`
- Auth: HTTP bearer

## Query parameters

- `mailbox` string, required
- `limit` integer
- `direction` 'inbound' | 'outbound'
- `trash` '1'
- `folder` string, uuid
- `q` string

## Response `200`

OK

- object
  - `messages` MessageSummary[]
    - `id` string, uuid
    - `direction` 'inbound' | 'outbound'
    - `from_address` string, nullable
    - `to_address` string, nullable
    - `subject` string, nullable
    - `size_bytes` integer
    - `received_at` string, date-time
    - `read_at` string, date-time, nullable
    - `deleted_at` string, date-time, nullable
    - `flagged_at` string, date-time, nullable
    - `folder_id` string, uuid, nullable
    - `delivery_status` 'sent' | 'deferred' | 'bounced' | 'null', nullable: Only ever populated for direction=outbound. null means either too recent to have a result yet, or delivered locally to another Mektup mailbox rather than over external SMTP.
    - `delivery_detail` string, nullable: The real SMTP response text from the recipient's mail server (Mektup has no relayhost, so its own MTA does the delivery attempt directly) - not a synthesized summary.
    - `delivery_checked_at` string, date-time, nullable
    - `thread_key` string
    - `thread_count` integer
    - `thread_has_unread` boolean

## Other responses

- `400`: Invalid request

---

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