---
title: "List inbox threads"
method: GET
path: "/api/e2/mail/threads"
tags: ["Inbox"]
---

# List inbox threads

`GET /api/e2/mail/threads`

List email threads (conversations) for your inbox with cursor-based pagination. This is the primary endpoint for building an inbox UI.

**What is a Thread?**
A thread groups related emails together based on the In-Reply-To and References headers, similar to how Gmail groups conversations. Each thread contains both inbound (received) and outbound (sent) messages.

**Use with /mail/threads/:id:**
Use this endpoint to list threads, then use `GET /mail/threads/:id` to fetch all messages in a specific thread.

## Query parameters

- `domain` string — Filter threads by domain. Accepts domain ID (e.g., 'dom_xxx') or domain name (e.g., 'example.com'). Returns threads where any participant email matches the domain.
- `address` string — Filter threads by email address. Accepts address ID (e.g., 'addr_xxx') or raw email address (e.g., 'user@example.com'). Returns threads where the address is a participant.
- `limit` string — Maximum number of threads to return (1-100). Default is 25.
- `cursor` string — Cursor for pagination. Pass the thread ID from `pagination.next_cursor` of the previous response to get the next page.
- `search` string — Search query to filter threads by subject or participant emails. Case-insensitive partial match.
- `unread` string — Filter by unread status. Set to 'true' to only return threads with unread messages.

## Response `200`

Response for status 200

- object
  - `threads` object[], required — Array of thread objects matching the query, sorted by last message date (newest first)
    - `id` string, required — Unique identifier for the thread
    - `root_message_id` string, required — RFC 2822 Message-ID of the first message in the thread
    - `normalized_subject` string, nullable — Normalized subject line (stripped of Re:, Fwd:, etc.) used for thread grouping
    - `participant_emails` string[], required — Array of all unique email addresses that have participated in this thread
    - `participant_names` string[], required — Array of formatted participant names in the format 'First Last <email@domain.com>' or just 'email@domain.com' if no name is available
    - `message_count` number, required — Total number of messages in the thread (both inbound and outbound)
    - `last_message_at` string, required — ISO 8601 timestamp of the most recent message in the thread
    - `created_at` string, required — ISO 8601 timestamp when the thread was created (first message received)
    - `latest_message` object, nullable
      - `id` string, required — Unique identifier of the message
      - `type` union, required — Whether the message was received (inbound) or sent (outbound)
        - 'inbound'
        - 'outbound'
      - `subject` string, nullable — Subject line of the message
      - `from_text` string, required — Formatted sender information (name and/or email)
      - `text_preview` string, nullable — First 200 characters of the message body as a preview
      - `is_read` boolean, required — Whether the message has been read (always true for outbound)
      - `has_attachments` boolean, required — Whether the message has any attachments
      - `date` string, nullable — ISO 8601 timestamp of when the message was sent/received
    - `has_unread` boolean, required — Whether the thread has any unread inbound messages
    - `is_archived` boolean, required — Whether the thread has been archived
    - `unread_count` number — Number of unread messages in the thread
  - `pagination` object, required — Pagination metadata for cursor-based pagination
    - `limit` number, required — Number of results per page
    - `has_more` boolean, required — Whether there are more threads available after this page
    - `next_cursor` string, nullable — Cursor to pass as the `cursor` parameter to fetch the next page. Null if no more results.
  - `filters` object, required — Applied filters for this query
    - `search` string — Applied search query
    - `unread_only` boolean — Whether filtering for unread threads only
    - `domain` string — Applied domain filter (resolved domain name)
    - `address` string — Applied address filter (resolved email address)

## Other responses

- `400` — Response for status 400
- `401` — Response for status 401
- `500` — Response for status 500

## Changes

- **2025-12-05** `5cfa3996fd95` — 1 info
  - added the required property `threads/items/participant_names` to the response with the `200` status
- **2025-12-04** `b31e27d78703` — 2 breaking, 3 info
  - for the `query` request parameter `limit`, default value `25` was added
  - for the `query` request parameter `unread`, default value `false` was added
  - api tag `Inbox` added
  - api tag `Mail` removed
  - …1 more

[Change history](https://skmtc.dev/inboundemail/apis/inbound-email-api/changes/api/e2/mail/threads/get.md)

---

[API](https://skmtc.dev/inboundemail/apis/inbound-email-api.md) · [All operations](https://skmtc.dev/inboundemail/apis/inbound-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inboundemail/inbound-email-api/revisions/04a8a5e5040d/schema)