Skip to Content

An RFC 8621 §4.4 FilterCondition; every key optional, conditions in one object AND together. At most one full-text condition (text/subject/body) per filter…

An RFC 8621 §4.4 FilterCondition; every key optional, conditions in one object AND together. At most one full-text condition (text/subject/body) per filter, never under OR/NOT. A full-text condition is at most 512 characters and 64 words; a substring needle (from/to/cc/bcc/header) at most 50 bytes. $deleted is refused.

type EmailSearchCondition = {
  after?: string
  allInThreadHaveKeyword?: string
  bcc?: string
  before?: string
  body?: string
  cc?: string
  from?: string
  hasAttachment?: boolean
  hasKeyword?: string
  header?: string[]
  inMailbox?: string
  inMailboxOtherThan?: string[]
  maxSize?: number
  minSize?: number
  noneInThreadHaveKeyword?: string
  notKeyword?: string
  someInThreadHaveKeyword?: string
  subject?: string
  text?: string
  to?: string
  [key: string]: unknown
}

Fields

FieldTypeDescription
afterstringOptional. Received at or after this RFC 8620 UTCDate (e.g. 2026-08-01T00:00:00Z)
allInThreadHaveKeywordstringOptional. Every live message in the conversation carries this keyword
bccstringOptional. Substring of the Bcc addresses (max 50 bytes)
beforestringOptional. Received strictly before this RFC 8620 UTCDate (e.g. 2026-08-01T00:00:00Z), the one place this API departs from epoch seconds
bodystringOptional. Full-text match over the body parts
ccstringOptional. Substring of the Cc addresses (max 50 bytes)
fromstringOptional. Substring of the From addresses (max 50 bytes)
hasAttachmentbooleanOptional. Whether the message has file attachments
hasKeywordstringOptional. The message carries this keyword or flag (e.g. $seen, $flagged, $forwarded)
headerstring[]Optional. [name] = the header is present; [name, value] = the header contains value. Indexed names only: subject, message-id, in-reply-to, from, to, cc, list-id
inMailboxstringOptional. Only messages in this Mailbox, as L<labelId>: the id from GET /mailboxes/{mailboxId}/labels prefixed with L (INBOX is usually L1)
inMailboxOtherThanstring[]Optional. Only messages in at least one Mailbox NOT listed (same L<labelId> ids)
maxSizenumberOptional. Size in bytes is strictly below this
minSizenumberOptional. Size in bytes is at least this
noneInThreadHaveKeywordstringOptional. No live message in the conversation carries this keyword
notKeywordstringOptional. The message does NOT carry this keyword
someInThreadHaveKeywordstringOptional. At least one live message in the conversation carries this keyword
subjectstringOptional. Full-text match over the Subject header
textstringOptional. Full-text match over the whole message (subject and bodies)
tostringOptional. Substring of the To addresses (max 50 bytes)

Used in

EmailSearchFilter.

On this page