# API · Messages & threads

{/* // READ + REPLY */}

Postern reconstructs threads from IMAP headers, so a message belongs to a thread and a reply stays in
that thread without you tracking `In-Reply-To` / `References` by hand.

## `GET /v1/inboxes/{addr}/messages` — list

| Query | Type | Notes |
|---|---|---|
| `direction` | `inbound` \| `outbound` | Filter by direction. |
| `unread_only` | bool | Inbound, unread only. |
| `limit` | int | Page size. |
| `cursor` | string | From a previous `next_cursor`. |

```bash frame="terminal"
curl -sS "$POSTERN_API_BASE_URL/v1/inboxes/agent7%40x4p.mszazu.com/messages?direction=inbound" \
  -H "Authorization: Bearer $POSTERN_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg_8Tz",
      "thread_id": "thread_9aB",
      "direction": "inbound",
      "from": "no-reply@acme.test",
      "to": ["agent7@x4p.mszazu.com"],
      "subject": "Verify your email",
      "snippet": "Your code is 492013…",
      "received_at": "2026-06-12T18:05:42Z",
      "unread": true
    }
  ],
  "next_cursor": null
}
```

## `GET /v1/messages/{id}` — get one

Returns the full message including `text`, `html`, and headers.

```bash frame="terminal"
curl -sS "$POSTERN_API_BASE_URL/v1/messages/msg_8Tz" \
  -H "Authorization: Bearer $POSTERN_API_KEY"
```

## `POST /v1/messages/{id}/reply` — reply in-thread

### Request

```json
{
  "text": "On it — thanks.",
  "html": "<p>On it — thanks.</p>",
  "idempotency_key": "reply-3"
}
```

```bash frame="terminal"
curl -sS -X POST "$POSTERN_API_BASE_URL/v1/messages/msg_8Tz/reply" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "On it — thanks." }'
```

### Response `202`

```json
{ "id": "msg_5dRk", "status": "queued", "thread_id": "thread_9aB" }
```

The reply's `In-Reply-To` and `References` are set server-side from the original message, so it lands
in the same conversation. Replies count toward [karma](https://docs.agents.mszazu.com/concepts/deliverability-and-karma/) — they
earn sending headroom back.

## `GET /v1/inboxes/{addr}/threads` — list threads

```bash frame="terminal"
curl -sS "$POSTERN_API_BASE_URL/v1/inboxes/agent7%40x4p.mszazu.com/threads" \
  -H "Authorization: Bearer $POSTERN_API_KEY"
```

```json
{
  "data": [
    { "id": "thread_9aB", "subject": "Verify your email", "message_count": 2, "updated_at": "2026-06-12T18:06:10Z" }
  ],
  "next_cursor": null
}
```

## `GET /v1/threads/{id}` — get one thread

Returns the thread with its ordered messages.

```bash frame="terminal"
curl -sS "$POSTERN_API_BASE_URL/v1/threads/thread_9aB" \
  -H "Authorization: Bearer $POSTERN_API_KEY"
```

## Next

- [wait_for_email](https://docs.agents.mszazu.com/api/wait/) — block for the next inbound message.
- [Webhooks](https://docs.agents.mszazu.com/api/webhooks/) — push inbound delivery.
- [Inboxes](https://docs.agents.mszazu.com/api/inboxes/) — create and send.