---
title: "List mailbox inbox thread attention states"
method: GET
path: "/mailboxes/{id}/inbox/threads"
tags: ["Mailboxes"]
---

# List mailbox inbox thread attention states

`GET /mailboxes/{id}/inbox/threads`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/inbox/threads`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Lists the deterministic attention queue with cursor-bound keyset pagination, anchored to the first page's message-time cutoff. Live state changes may add or remove rows; use reply-scans when a frozen historical candidate set is required. Defaults to needs_reply, oldest first.

## Query parameters

- `attention_state` 'needs_reply' | 'waiting_on_them' | 'done' | 'follow_up_due' | 'delivery_failed' | 'no_action'
- `sort_by` 'attention_since' | 'last_message_at'
- `order` 'asc' | 'desc'
- `after` string, date-time
- `before` string, date-time
- `cursor` string
- `limit` integer

## Headers

- `X-Shipmail-Organization` string

## Response `200`

Attention queue page and state counts.

- InboxThreads
  - `object` 'inbox_threads', required
  - `mailbox_id` string, required
  - `data` InboxThreadSummary[], required
    - `object` 'inbox_thread_summary', required
    - `id` string, required
    - `thread_id` string, required: Deprecated and not stable: a legacy thread ID that changes when the mail server re-threads its IDs or a relayed send's placeholder key is replaced. It remains supported in thread paths; store conversation_id instead.
    - `conversation_id` string, required: Stable Shipmail conversation identifier (thd_...). Store this: it survives thread merges and mail-server re-threading, which thread_id does not.
    - `attention_state` 'needs_reply' | 'waiting_on_them' | 'done' | 'follow_up_due' | 'delivery_failed' | 'no_action', required
    - `version` integer, required
    - `attention_since` string, date-time, nullable, required
    - `done_at` string, date-time, nullable, required
    - `follow_up_at` string, date-time, nullable, required
    - `assigned_member_id` string, nullable, required
    - `subject` string, nullable, required
    - `latest_from_address` string, nullable, required
    - `message_count` integer, required
    - `first_message_at` string, date-time, required
    - `last_message_at` string, date-time, required
    - `latest_message_id` string, nullable, required: Shipmail tracked message ID.
    - `latest_email_id` string, nullable, required: Provider/JMAP email ID.
    - `latest_inbound_message_id` string, nullable, required
    - `latest_inbound_email_id` string, nullable, required
    - `latest_inbound_at` string, date-time, nullable, required
    - `latest_outbound_message_id` string, nullable, required
    - `latest_outbound_email_id` string, nullable, required
    - `latest_outbound_at` string, date-time, nullable, required
  - `summary` object, required
  - `pagination` object, required
    - `limit` integer, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required
    - `snapshot_at` string, date-time, required

## Other responses

- `401`: Authentication failed.
- `403`: Insufficient permissions.
- `404`: Resource not found.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

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