Guide

IMAP SEARCH Syntax Reference

IMAP defines its SEARCH command in RFC 9051, with search keys like FROM, SUBJECT, SINCE, UNSEEN, HEADER, TEXT, and BODY. Each one filters the mailbox on the server before any message is downloaded. This reference explains what every common search key does, how keys combine, and how the CLI search flags map onto the same IMAP keys so you get the same results across Gmail, Outlook, and any IMAP server without opening a raw connection.

Written by Prem Keshari Senior SRE

Verified — CLI 3.1.17 · Gmail, Outlook, IMAP · last tested June 9, 2026

Command references used in this guide: nylas email search, nylas email list, and nylas email folders.

What are the IMAP SEARCH keys in RFC 9051?

IMAP SEARCH keys are filter criteria the mail server evaluates before sending any message back to the client. RFC 9051 defines roughly 30 keys, grouped into address keys (FROM, TO), flag keys (SEEN, UNSEEN), date keys (SINCE, BEFORE), and content keys (SUBJECT, TEXT, BODY).

The server returns a list of message sequence numbers or UIDs that match, and the client fetches only those. That server-side filtering is why IMAP search scales: a mailbox with 50,000 messages returns a few hundred matches without downloading the rest. RFC 9051, published in August 2021, is IMAP4rev2; it supersedes RFC 3501 (IMAP4rev1) but keeps the same SEARCH grammar, so the keys below work on both. According to RFC 9051 Section 6.4.4, string searches like SUBJECT are case-insensitive substring matches, not exact matches.

# RFC 9051 SEARCH key families (the ones you actually use):
#   FROM "addr"      address keys  -> sender / recipient
#   TO "addr"
#   SUBJECT "text"   header keys   -> substring, case-insensitive
#   HEADER name val
#   SINCE 1-Jun-2026 date keys     -> internal-date comparisons
#   BEFORE 1-Jul-2026
#   UNSEEN / SEEN    flag keys     -> read state, no value
#   FLAGGED          flag key      -> the "starred" flag
#   TEXT "text"      content keys  -> headers + body
#   BODY "text"                    -> body only

How do the CLI search flags map to IMAP keys?

The nylas email search flags map one-to-one onto the IMAP SEARCH keys, so you express the same filter without speaking raw IMAP. The --from flag is the FROM key, --subject is SUBJECT, --after is SINCE, and --unread is UNSEEN.

The query string argument behaves like the IMAP TEXT key: it matches headers and body text. Pass "*" as the query to search on flags alone. The default result limit is 20, and the tool auto-paginates past 200 when you raise --limit. Combining flags applies an implicit AND, exactly like listing multiple keys in an IMAP SEARCH command. This holds across all 6 supported providers because the CLI normalizes provider quirks behind one API.

CLI flagIMAP keyMatches
--fromFROMSender address substring
--toTORecipient address substring
--subjectSUBJECTSubject substring
--afterSINCEInternal date on or after
--beforeBEFOREInternal date before
--unreadUNSEENUnread flag set
--starredFLAGGEDFlagged/starred

How do I combine FROM, SINCE, and UNSEEN in one query?

Combining keys narrows the result set with an implicit AND: IMAP returns only messages that satisfy every key you list. To find unread mail from a single sender since the start of the month, pass --from, --after, and --unread together. The server intersects all three before returning UIDs.

The command below runs the equivalent of FROM "alerts@stripe.com" SINCE 1-Jun-2026 UNSEEN as a single server-side filter. Dates use YYYY-MM-DD, which the tool converts to the IMAP DD-Mon-YYYY date format. Adding --json emits structured output you can pipe to jq; this returns matches in roughly one network round trip rather than fetching the whole folder. Scope it with --in to one folder when you know where the mail lives.

# Unread mail from one sender since June 1, server-side filtered:
nylas email search "*" \
  --from "alerts@stripe.com" \
  --after 2026-06-01 \
  --unread \
  --in INBOX \
  --limit 50 --json | jq '.[] | {subject, date}'

# List the folders you can scope to first:
nylas email folders list --json

When should I use HEADER, TEXT, or BODY?

These three IMAP keys differ in what part of the message they read. HEADER matches a named header field and its value, BODY matches the message body only, and TEXT matches both headers and body. Pick the narrowest key that finds your message, because broader keys scan more data per message.

Use HEADER List-Id newsletter to catch mailing-list traffic that SUBJECT would miss. The CLI query argument behaves like TEXT, so a bare query string searches headers and body together. There is a real performance trade-off: a 2021 RFC 9051 note warns that BODY and TEXT searches may be slow on large mailboxes because the server scans full message text, while FROM and SUBJECT hit indexed headers. Gmail's IMAP layer, documented in Google's IMAP extensions reference, maps these onto its own search engine, so phrase matching can differ slightly from a strict RFC server.

# TEXT-style: bare query scans headers + body for "invoice"
nylas email search "invoice" --limit 20 --json

# HEADER-style: target a specific header value (List-Id) via the query
nylas email search "newsletter" --from "list@discuss.example.com" --json

Why do providers treat BODY and TEXT differently?

Not every IMAP backend implements RFC 9051 SEARCH the same way, so BODY and TEXT can return different results per provider. Gmail rewrites IMAP search into its native query engine and ignores some literal substring rules; Outlook over IMAP honors header keys reliably but is slower on full-text body scans. The CLI hides these differences behind one normalized search.

Gmail's IMAP extensions, per Google's official reference, add the X-GM-RAW key for native Gmail search operators, which standard RFC clients don't expose. Microsoft enabled IMAP on Exchange Online but deprecated Basic Auth for it in 2022, so modern Outlook IMAP requires OAuth. Because providers diverge on the content keys, lean on the indexed keys (FROM, SUBJECT, SINCE) for portable filters, and treat BODY matches as best-effort. The command below runs the same flags against two grants to compare what each backend returns.

# Same filter, two grants — compare provider behavior on a body match
nylas email search "refund issued" --after 2026-05-01 --json | jq 'length'

# Indexed keys are portable across Gmail, Outlook, and generic IMAP:
nylas email search "*" --from "billing@vendor.com" --subject "receipt" --json

Next steps