Skip to content

API · Messages & threads

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`.

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

{
  "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.

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

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

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`

{ "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 — they earn sending headroom back.

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

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

{
  "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.

curl -sS "$POSTERN_API_BASE_URL/v1/threads/thread_9aB" \
  -H "Authorization: Bearer $POSTERN_API_KEY"

Next

wait_for_email — block for the next inbound message.
Webhooks — push inbound delivery.
Inboxes — create and send.