# Full-text search a mailbox

Searches email messages across subject, sender/recipient addresses, and body text using BM25 relevance ranking. Optionally filter by label, flags, or group matches by thread.

## `GET /api/v1/mailboxes/{mailboxId}/search`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `q` (string, required, max 512 chars) — Search keywords or phrases
- `label` (string) — Restrict search to a specific label or folder
- `excludeRoles` ("inbox" | "sent" | "drafts" | "trash" | "archive" | "junk"[]) — System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.
- `hasFlags` (string) — Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)
- `notFlags` (string) — Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)
- `limit` (integer, ≥ 1, ≤ 2000) — Maximum messages to return (default 25, max 100 — or 2000 with `fields=ids`)
- `cursor` (string) — Pagination cursor for next page of results
- `fields` ("ids") — `ids`: answer the matching message IDS only, in rank order, under `ids` — no metadata rows, page cap 2000. What a client that needs a UID set (IMAP SEARCH) asks for: one call for what used to be twenty pages of full rows. Not combinable with `group` or `snippet`.
- `group` ("thread") — Collapse matches to one top-ranked message per conversation thread
- `snippet` ("true" | "false") — Whether to include highlighted search text snippets in results

### Responses

**200** — Ranked search results

`application/json` → object

- `results` (MessageMeta[], required)
  - `auth` (MessageAuth, required) — Stored SMTP authentication and original inbound junk verdicts. Missing verdicts are null; the object is null when none were recorded (including APPEND and local Sent copies). Junk does not follow later label changes.
    - `arc` (string | null, required) — ARC verdict, or null
    - `dkim` (string | null, required) — DKIM verdict, or null
    - `dmarc` (string | null, required) — DMARC verdict, or null
    - `junk` (boolean | null, required) — The inbound spam verdict (X-OpenEmail-Junk), or null when none was stamped
    - `spf` (string | null, required) — SPF verdict (pass/fail/softfail/none/...), or null
  - `bcc` (array | null, required) — Parsed Bcc header addresses for composed drafts, or null
  - `blobGen` (string, required) — Storage generation identifier
  - `blobHash` (string, required) — SHA-256 hash of raw MIME content in storage
  - `cc` (array | null, required) — Parsed Cc header addresses, or null if unparseable
  - `deliveryMeta` (object | null, required) — Inbound delivery audit metadata
  - `deliveryState` ("queued" | "relayed" | "delivered" | "failed" | "mixed" | null, required) — What became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery.
    - _option 1: "queued" | "relayed" | "delivered" | "failed" | "mixed"_
    - _option 2: null_
    - _option 3: null_
  - `envelopeFrom` (string, required) — SMTP envelope sender address
  - `envelopeTo` (string, required) — SMTP envelope recipient address
  - `flags` (string[], required) — System flags (seen, answered, flagged, draft, deleted)
  - `from` (array | null, required) — Parsed From header addresses, or null if unparseable
  - `hasAttachment` (boolean | null, required) — True if message has file attachments, null if not yet determined
  - `id` (string, required) — Unique message identifier (ULID)
  - `inReplyTo` (string | null, required) — In-Reply-To header Message-ID, or null
  - `keywords` (string[], required) — Custom JMAP keywords (e.g. $forwarded)
  - `labels` (MessageLabel[], required) — Labels attached to this message with per-label UIDs
    - `deleted` (boolean, required) — This membership's IMAP \Deleted mark (set with `flagLabel` on PATCH, acted on by POST /labels/{label}/expunge). Always present; false when unmarked. Per label, so the same message can be marked in one folder and clean in another
    - `modseq` (integer <int64>, required) — RFC 7162 MODSEQ change sequence number
    - `name` (string, required) — Label name
    - `uid` (integer <int64>, required) — Message UID inside this label
    - `uidValidity` (integer <int64>, required) — UID validity epoch of the label
  - `messageIdHeader` (string | null, required) — Message-ID header value, or null
  - `receivedAt` (integer <int64>, required) — Timestamp when message was received by server in epoch seconds
  - `referencesIds` (string[], required) — List of Message-IDs from References header
  - `sentAt` (integer | null, required) — Sent timestamp from Date header in epoch seconds, or null
  - `size` (integer <int64>, required) — Total message size in bytes
  - `snippet` (string | null, required) — Short plain-text preview of message body
  - `subject` (string | null, required) — Message subject line, or null
  - `threadId` (string | null, required) — Conversation thread identifier (ULID), or null
  - `to` (array | null, required) — Parsed To header addresses, or null if unparseable
  - `modseq` (integer <int64>) — Per-label MODSEQ (present in label UID listings)
  - `restoresTo` (array | null) — Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.
  - `uid` (integer <int64>) — Per-label UID (present in label UID listings)
- `ids` (string[]) — With `fields=ids`: the matching message IDs in rank order (`results` is then empty)
- `nextCursor` (string) — Opaque cursor for the next page; absent on the last page
- `scanWindow` (integer) — The ranking window's size: the results were drawn from the newest this-many matching messages. Present only beside `truncated`, so a client can say "more than N matches" with the N the server applied.
- `snippets` (EmailSearchSnippet[]) — Highlighted search excerpts
  - `id` (string, required) — Message ULID this snippet belongs to
  - `preview` (string | null, required) — Highlighted HTML snippet for the message body, or null if not matched
  - `subject` (string | null, required) — Highlighted HTML snippet for the subject line, or null if not matched
- `total` (integer) — Exact number of matching messages, under the same label and flag filters as the results. Absent when `truncated` (the ranking window clipped, so the count would describe the window rather than the match set) or when the page is past the end; absent also on grouped (`group=thread`) responses, whose conversation count is not known. Absent means unknown, never zero.
- `truncated` (boolean) — True if query matched more messages than maximum ranking window

**400** — validation_failed, empty_query, invalid_cursor, search_offset_too_deep, or grouped_search_unpaginated (grouped mode cannot be combined with cursor paging)

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/search' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.search.fullText`](/docs/sdks/typescript/search/full-text)

```ts
for await (const messageMeta of openemail.search.fullText(mailboxId, { q: '…' })) {
  // every item of every page (await the call instead for one page)
}
```
