---
title: "List threads in an inbox"
method: GET
path: "/v1/threads"
tags: ["Mail"]
---

# List threads in an inbox

`GET /v1/threads`

## Request

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

Every thread in one inbox, newest activity first, with its messages. Keyset pagination: pass the previous page's `next_cursor` as `cursor` until `next_cursor` is `null`. A page can hold fewer than `limit` threads, even none, and still have a `next_cursor`. There is no date filter: to sync, walk the whole inbox (see the guide). A thread that gets new activity mid-walk moves to the front, so the next walk picks it up.

Unsent drafts and scheduled sends are never returned: threads holding only those are skipped. Subjects, snippets, attachment file names and ids, and to-do summaries need `mail.content.read`.

**Scope:** `mail.metadata.read`. **Rate limit class:** `read` (600/minute per key).

## Query parameters

- `inbox_id` string, uuid, required
- `limit` integer
- `cursor` string

## Response `200`

OK

- ThreadPage
  - `threads` Thread[], required
    - `id` string, required: Provider thread id (unique within the inbox).
    - `inbox_id` string, uuid, required
    - `inbox_email` string, required
    - `owner_email` string, required
    - `category` string, nullable, required: Slashy category, e.g. `Important` or one of the team's own.
    - `labels` string[], required: Union of the messages' labels.
    - `first_message_at` string, date-time, nullable, required
    - `last_message_at` string, date-time, nullable, required
    - `todo` Todo, required: Slashy's to-do on the thread.
      - `type` string, required: `reply` (they're waiting on us), `followup` (we're waiting on them) or `dismissed` (reviewed, no action).
      - `urgency` string, nullable, required: `high`, `medium` or `low`.
      - `due_at` string, date-time, nullable, required
      - `updated_at` string, date-time, nullable, required
      - `summary` string, nullable: One-line description of what needs doing. Present only when the key has `mail.content.read`.
    - `message_count` integer, required
    - `messages` Message[], required: Oldest first.
      - `id` string, required: Provider message id (unique within the inbox).
      - `message_id` string, nullable, required: RFC 5322 `Message-ID` header.
      - `in_reply_to` string, nullable, required: `In-Reply-To` header.
      - `date` string, date-time, nullable, required: When it was sent.
      - `received_at` string, date-time, nullable, required: When it was delivered to this inbox.
      - `from` Participant, required
        - `email` string, required
        - `name` string, nullable, required
      - `to` Participant[], required
        - `email` string, required
        - `name` string, nullable, required
      - `cc` Participant[], required
        - `email` string, required
        - `name` string, nullable, required
      - `bcc` Participant[], required
        - `email` string, required
        - `name` string, nullable, required
      - `labels` string[], required: Provider labels. For Gmail these are label ids: `INBOX`, `SENT`, `UNREAD`, `CATEGORY_UPDATES`, `Label_123` and so on.
      - `is_read` boolean, required
      - `is_starred` boolean, required
      - `is_sent` boolean, required
      - `is_trash` boolean, required
      - `is_spam` boolean, required
      - `size_bytes` integer, required
      - `attachments` Attachment[], required
        - `mime_type` string, nullable, required
        - `size_bytes` integer, nullable, required
        - `filename` string, nullable: Present only when the key has `mail.content.read`.
        - `id` string, nullable: Download it from `/v1/attachments/{inbox_id}/{message_id}/{id}`. Present only when the key has `mail.content.read`.
        - `content_id` string, nullable: The part's Content-ID, without `<>`. An inline image appears in the HTML body as `cid:<content_id>`. Present only when the key has `mail.content.read`.
      - `subject` string: Empty string when there is none. Present only when the key has `mail.content.read`.
      - `snippet` string: Short preview of the body. Present only when the key has `mail.content.read`.
    - `subject` string: The first message's subject. Present only when the key has `mail.content.read`.
  - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; `null` on the last page.

## Other responses

- `400`: Bad request. `error` is one of: `invalid_cursor`.
- `401`: Missing, malformed, unknown, revoked or expired API key. `error` is one of: `invalid_api_key`, `api_key_revoked`, `api_key_expired`.
- `403`: The key is valid but may not make this call. `error` is one of: `browser_not_allowed`, `ip_not_allowed`, `not_enterprise`, `key_owner_inactive`, `insufficient_scope`.
- `404`: Not found, or not readable by this key (the two look the same). `error` is one of: `inbox_not_found`.
- `422`: A parameter is missing or invalid. The body lists each problem (not the `Error` shape).
- `429`: Too many requests. Wait `Retry-After` seconds, then retry. `error` is one of: `too_many_auth_failures`, `rate_limited`, `too_many_concurrent_requests`.
- `503`: Temporarily unavailable. Retry the same request later. `error` is one of: `page_unavailable`.

---

[API](https://skmtc.dev/slashy/apis/slashy-enterprise-api.md) - [All operations](https://skmtc.dev/slashy/apis/slashy-enterprise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/slashy/apis/slashy-enterprise-api/revisions/49841c75ad9f?raw)