# search.fullText

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.

```ts
openemail.search.fullText(
  mailboxId: string,
  options: SearchFullTextOptions,
): PagePromise<SearchFullTextResult, MessageMeta | string>
```

It calls `GET /mailboxes/{mailboxId}/search`: [Full-text search a mailbox](/docs/api/messages/get_MailboxSearch) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |

## Options

The last argument, `options`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `q` | `string` | query `q` | Required. Search keywords or phrases |
| `label` | `string` | query `label` | Restrict search to a specific label or folder |
| `excludeRoles` | `('inbox' \| 'sent' \| 'drafts' \| 'trash' \| 'archive' \| 'junk')[]` | query `excludeRoles` | System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed. |
| `hasFlags` | `string` | query `hasFlags` | Comma-separated flag names; a message matches only if ALL are set (e.g. flagged) |
| `notFlags` | `string` | query `notFlags` | Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only) |
| `limit` | `number` | query `limit` | Maximum messages to return (default 25, max 100 — or 2000 with `fields=ids`) |
| `cursor` | `string` | query `cursor` | Pagination cursor for next page of results |
| `fields` | `'ids'` | query `fields` | `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'` | query `group` | Collapse matches to one top-ranked message per conversation thread |
| `snippet` | `boolean` | query `snippet` | Whether to include highlighted search text snippets in results |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

It is a listing, a [`PagePromise`](/docs/sdks/typescript/listings). Awaited, it is one page as the API answers it, [`SearchFullTextResult`](#searchfulltextresult). Iterated with `for await`, it is every [`MessageMeta`](/docs/sdks/typescript/types/message-meta) | `string` of every page, each page fetched as the loop reaches it.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed, empty_query, invalid_cursor, search_offset_too_deep, or grouped_search_unpaginated (grouped mode cannot be combined with cursor paging) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `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) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### SearchFullTextResult

```ts
/** What `search.fullText` answers. */
type SearchFullTextResult = {
  /** With `fields=ids`: the matching message IDs in rank order (`results` is then empty) */
  ids?: string[]
  /** Opaque cursor for the next page; absent on the last page */
  nextCursor?: string
  results: MessageMeta[]
  /** 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. */
  scanWindow?: number
  /** Highlighted search excerpts */
  snippets?: EmailSearchSnippet[]
  /** 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. */
  total?: number
  /** True if query matched more messages than maximum ranking window */
  truncated?: boolean
}
```

It names these types of the API, each on a page of its own: [`EmailSearchSnippet`](/docs/sdks/typescript/types/email-search-snippet), [`MessageMeta`](/docs/sdks/typescript/types/message-meta).
