EmailSearchRequest
The EmailSearchRequest type of the TypeScript SDK, which search.query take or answer.
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 | 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[] | Optional. Up to 4 comparators; an id tiebreak is always appended so the order is total. |
Used by
| Method | What it does |
|---|---|
search.query | Structured filter and query messages |