---
title: "Search messages"
method: GET
path: "/v1/search"
tags: ["Mail"]
---

# Search messages

`GET /v1/search`

## Request

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

Messages matching a Gmail-style query across the inboxes the key can read, newest first. Returns references; fetch the thread for details. Drafts are never returned.

Any key can use `from:`, `to:`, `cc:`, `bcc:`, `label:`, `is:`, `in:`, `has:`, `after:`, `before:`, `newer_than:`, `older_than:`, `larger:`, `smaller:`, `size:`, `category:` and `todo:`, combined with `OR`, `-` and spaces (AND). Free text, `subject:` and `filename:` need `mail.content.read` (`insufficient_scope` otherwise). `me` (as in `from:me`) and `assigned:` are not supported. A query may have at most 25 parts, counting each term and each AND/OR that joins two (`from:a to:b` is 3).

Offset pagination: pass `next_offset` as `offset` until it is `null`. `offset + limit` may not exceed 10,000; narrow the query to see further.

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

## Query parameters

- `q` string, required
- `inbox_id` string[]
- `limit` integer
- `offset` integer

## Response `200`

OK

- SearchPage
  - `results` SearchResult[], required
    - `inbox_id` string, uuid, required
    - `thread_id` string, required
    - `message_id` string, required: Same as `Message.id`.
    - `date` string, date-time, nullable, required: When the message was sent.
  - `next_offset` integer, nullable, required: Pass as `offset` for the next page; `null` when there is none.

## Other responses

- `400`: Bad request. `error` is one of: `window_exceeded`, `invalid_query`, `query_too_complex`, `unsupported_operator`.
- `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`.
- `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: `search_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)