Explaining IMAP Search Criteria

An IMAP criteria specifies which messages to match within the currently selected mailbox. These criteria can test message attributes like sender, recipient, subject, dates, flags, size, and more.

Basic Structure

The search criteria is a space-separated list of conditions (logical AND). Use parentheses for nesting or combining with OR/NOT.

Common Search Criteria

Criterion	Description
ALL	Matches all messages
ANSWERED	Messages with the `\Answered` flag
DELETED	Messages with the `\Deleted` flag
DRAFT	Messages with the `\Draft` flag
FLAGGED	Messages with the `\Flagged` flag
NEW	Messages with the `\Recent` flag but not `\Seen`
OLD	Messages that are not `\Recent`
RECENT	Messages with the `\Recent` flag
SEEN	Messages with the `\Seen` flag
UNANSWERED, UNDELETED, etc.	Opposites of the above

Header Criteria

Criterion	Description
`FROM <string>`	Matches sender
`TO <string>`	Matches recipient
`CC <string>`	Matches CC
`BCC <string>`	Matches BCC
`SUBJECT <string>`	Matches subject
`BODY <string>`	Matches body content
`TEXT <string>`	Matches subject, body, or headers

Date Criteria

Criterion	Description
`BEFORE <date>`	Before the date
`ON <date>`	On the date
`SINCE <date>`	On or after the date
`SENTBEFORE <date>`	Based on Date header (not delivery date)
`SENTON <date>`	Based on Date header
`SENTSINCE <date>`	Based on Date header

Date format: "DD-Mon-YYYY" (e.g., "01-Apr-2025")

ID and Size Criteria

Criterion	Description
`LARGER <n>`	Size in octets greater than n
`SMALLER <n>`	Size in octets less than n
`UID <sequence>`	Match by UID instead of message sequence
`HEADER <field> <value>`	Match specific header fields

Logical Operators

Operator	Example	Description
`NOT`	`NOT SEEN`	Negation
`OR`	`OR DELETED SEEN`	Logical OR
`( )`	`(FROM "alice@example.com" SEEN)`	Grouping for complex expressions

Examples

FROM "bob@example.com" SINCE 01-Jan-2024
NOT SEEN
OR FROM "alice@example.com" SUBJECT "meeting"
SUBJECT "réunion"

Prefix Notation

The IMAP "SEARCH" command uses a form of prefix notation (Polish notation) when expressing complex search criteria, particularly with logical operators like "NOT", "OR", and "AND".

What Is Prefix (Polish) Notation?

In prefix notation, the operator comes before the operands. This avoids the need for parentheses to indicate precedence and grouping.

IMAP's Use of Prefix Notation

In IMAP "SEARCH", logical operators like "NOT" and "OR" are written before their search conditions — just like in Polish notation.

Example 1: Negation

NOT SEEN

This means: messages that are not seen.
"NOT" is the operator; "SEEN" is the operand.

Example 2: Logical OR

OR DELETED SEEN

This means: messages that are either deleted or seen.
"OR" is the operator; "DELETED" and "SEEN" are operands.

Example 3: Nested Grouping

OR (FROM "alice@example.com") (SUBJECT "meeting")

This finds messages either from Alice or with subject "meeting".

You can also write:

OR FROM "alice@example.com" SUBJECT "meeting"

Notes on IMAP Search Behavior

Multiple criteria given without an operator are treated as implicit AND.
```
FROM "bob" SEEN
```
is equivalent to:
```
AND FROM "bob" SEEN  (implicit)
```

IMAP doesn’t define an explicit "AND" operator — it’s just inferred.

Summary

IMAP uses prefix notation:

Operators come before operands.
Useful for expressing logic like "NOT", "OR".
Implies "AND" by default for multiple criteria.
Avoids ambiguity by using clear order and optional parentheses.