# EmailSearchRequest

The EmailSearchRequest type of the TypeScript SDK, which search.query take or answer.

```ts
type EmailSearchRequest = {
  calculateTotal?: boolean
  collapseThreads?: boolean
  excludeRoles?: ('inbox' | 'sent' | 'drafts' | 'trash' | 'archive' | 'junk')[]
  fields?: 'ids'
  filter?: EmailSearchFilter
  limit?: number
  position?: number
  snippet?: boolean
  sort?: EmailSearchComparator[]
}
```

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `calculateTotal` | `boolean` | Optional. Also return the total number of matches (an extra count). |
| `collapseThreads` | `boolean` | Optional. Return one representative message per conversation. |
| `excludeRoles` | `('inbox' \| 'sent' \| 'drafts' \| 'trash' \| 'archive' \| 'junk')[]` | Optional. System label roles whose mail this query must not return — e.g. `["trash", "junk"]` for an All-Mail view. A message carrying ANY label with one of these roles is excluded, whatever else it carries. Says in one argument what a filter would need a label lookup and one bound value per label to say; a role no label answers to is simply not excluded. |
| `fields` | `'ids'` | Optional. `ids`: answer the matching message IDS only, in query order, under `ids` — no metadata rows, page cap 2000. For a client that needs an id set (an IMAP SEARCH with header or BODY criteria) and would otherwise download bodies to decide. Not combinable with `snippet`. |
| `filter` | [`EmailSearchFilter`](/docs/sdks/typescript/types/email-search-filter) | Optional.  |
| `limit` | `number` | Optional. Page size; capped at 200, defaults to 25 — or up to 2000 with `fields: "ids"`. |
| `position` | `number` | Optional. Zero-based offset into the result list. A negative value counts back from the end (RFC 8620 §5.5). |
| `snippet` | `boolean` | Optional. Also return highlighted \<mark> excerpts (subject + body preview) for the matched text terms of this page's results. Each excerpt costs a body read, so at most the first 50 results carry one. |
| `sort` | [`EmailSearchComparator[]`](/docs/sdks/typescript/types/email-search-comparator) | Optional. Up to 4 comparators; an id tiebreak is always appended so the order is total. |

## Used by

| Method | What it does |
| --- | --- |
| [`search.query`](/docs/sdks/typescript/search/query) | Structured filter and query messages |
