Skip to Content

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

FieldTypeDescription
calculateTotalbooleanOptional. Also return the total number of matches (an extra count).
collapseThreadsbooleanOptional. 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.
filterEmailSearchFilterOptional.
limitnumberOptional. Page size; capped at 200, defaults to 25 — or up to 2000 with fields: "ids".
positionnumberOptional. Zero-based offset into the result list. A negative value counts back from the end (RFC 8620 §5.5).
snippetbooleanOptional. 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.
sortEmailSearchComparator[]Optional. Up to 4 comparators; an id tiebreak is always appended so the order is total.

Used by

MethodWhat it does
search.queryStructured filter and query messages

On this page