---
title: "Search mail"
method: GET
path: "/api/v1/search"
tags: ["Threads"]
---

# Search mail

`GET /api/v1/search`

## Request

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

Full-text search with operators: `from:`, `to:`, `subject:`, `label:`, `has:attachment`, `is:unread`, `is:starred`, `before:YYYY-MM-DD`, `after:YYYY-MM-DD`, quoted phrases. Searches every folder except trash and spam unless `folder` is given.

## Query parameters

- `q` string, required
- `mailbox` string
- `folder` 'inbox' | 'sent' | 'drafts' | 'archive' | 'spam' | 'trash' | 'starred' | 'snoozed' | 'all'
- `cursor` string
- `limit` integer

## Response `200`

Matching 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)