---
title: "List threads"
method: GET
path: "/api/v1/threads"
tags: ["Threads"]
---

# List threads

`GET /api/v1/threads`

## Request

- Base URL: `https://supermailos.com`
- URL: `https://supermailos.com/api/v1/threads`
- Auth: HTTP bearer

Conversations across the mailboxes this key can read, newest first. Never marks anything read.

## Query parameters

- `mailbox` string
- `folder` 'inbox' | 'sent' | 'drafts' | 'archive' | 'spam' | 'trash' | 'starred' | 'snoozed' | 'all'
- `unread` boolean
- `label` string
- `hasAttachments` boolean
- `q` string
- `cursor` string
- `limit` integer

## Response `200`

A page of threads.

- ThreadList
  - `threads` Thread[], required
    - `id` string, required
    - `mailboxId` string, required
    - `mailbox` string, email, required: The mailbox's address.
    - `receivedOn` string, email, required: Where the conversation arrived (an alias, if so) or the address it was sent from.
    - `subject` string, required
    - `snippet` string, required
    - `from` EmailAddress, required
      - `email` string, email, required
      - `name` string
    - `participants` EmailAddress[], required: From/To/Cc of every message — never Bcc.
      - `email` string, email, required
      - `name` string
    - `folder` 'inbox' | 'sent' | 'drafts' | 'archive' | 'spam' | 'trash', required
    - `unread` boolean, required
    - `starred` boolean, required
    - `labels` string[], required
    - `lastMessageAt` string, date-time, required
    - `snoozedUntil` string, date-time
    - `hasAttachments` boolean, required
    - `messageCount` integer, required
  - `nextCursor` string, nullable, required: Pass as `cursor` for the next page.
  - `unread` integer, required: Unread conversations matching the filters (all pages).

## Other responses

- `400`: The request is malformed.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `429`: Too many requests.

---

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