Search
Search operators, dates and boolean logic, and how Airpost runs a search against the local index.
Type in the search bar at the top of the message list. Plain words match anywhere in a thread, and operators narrow the results. Search runs against an index on your computer, so it works offline and never sends your query to a server.
To jump to the search bar, use Edit > Find > Find in Mailbox, or press / with the Gmail shortcut set (F3 or mod+E with Outlook, mod+Alt+F with Apple Mail).
Operators
| Operator | Matches | Example |
|---|---|---|
from: | Sender name or address | from:alice |
to: | Any recipient: To, Cc or Bcc, by name or address | to:team@example.com |
subject: | Words in the subject | subject:invoice |
in: | A folder or label: inbox, sent, archive, trash, spam, drafts, or a folder or label name | in:inbox, in:receipts |
is:unread / is:read | Read state | is:unread |
is:starred / is:unstarred | Starred state | is:starred |
has:attachment | Threads with attachments (has:attachments also works) | has:attachment |
after: / since: | On or after a day (the day is included) | after:2024-03-01 |
before: | Before a day (the day is excluded) | before:"last week" |
Operators and AND, OR, NOT are case-insensitive. Put values with spaces in double quotes: subject:"q3 plan".
There is no label:, cc:, -term or larger:. Use in:<label> for labels, to: for Cc and Bcc, and NOT to exclude.
Combining terms
| Syntax | Meaning | Example |
|---|---|---|
a b or a AND b | Both | from:alice has:attachment |
a OR b | Either | from:alice OR from:bob |
a NOT b | a but not b | invoice NOT in:trash |
( ) | Grouping | subject:"q3 plan" NOT (in:trash OR in:spam) |
NOT applies to everything after it up to a closing ) or an OR. So is:unread NOT hello AND in:inbox means unread mail that isn’t (hello in the inbox). Use parentheses when in doubt.
Dates
before:, after: and since: take a day, resolved in your time zone:
| Form | Examples |
|---|---|
| ISO dates | 2024-03-01, 2024/3/1, 2024.03.01 |
| A month | 2024-03, march, march 2024 (the 1st of the month) |
| Month and day | mar 1, 1 mar, "march 1st, 2024", "1 march 2024" |
| Weekdays | monday, mon, tues |
| Relative | today, yesterday, "3 days ago", 2w, 6m, 1y, "last month" |
A date without a year, or a weekday, means the most recent one on or before today. Short forms are Nd, Nw, Nm and Ny for days, weeks, months and years.
A date Airpost can’t read is an error rather than an empty result, so you know when it wasn’t understood.
How a search runs
Search never asks your mail provider. The engine keeps a full-text index (SQLite FTS5) next to your mail, with one row per thread, and answers every query from it.
Indexing
As messages sync, the engine adds each one to its thread’s index row: the subject, the sender and recipient names and addresses, the thread’s folders and labels, and the first 5,000 characters of each message body. The index uses Porter stemming, so invoice also finds invoices and invoiced.
Parsing
The query is parsed into a tree of AND, OR and NOT nodes. A word is an operator only when a : follows it, so trip to paris is three plain words. A word glued to a colon, like re:hello or http://example.com, stays one word.
Matching
Words and the from:, to:, subject: and in: operators become one FTS5 match, each value matched as a prefix: from:ann finds anna@example.com. is:, has: and dates become filters on the thread itself.
Results
Matching threads come back newest first.
Because the body index holds the start of each message, a word that appears only deep in a very long message may not match. Bodies are indexed once they’ve been downloaded; mail that has only its headers synced matches on subject and participants.
Errors you may see
Airpost refuses a query it can’t run instead of quietly showing nothing:
| Query | Why |
|---|---|
is:important | is: only takes read, unread, starred or unstarred |
has:pdf | has: only takes attachment or attachments |
from: | An operator needs a value |
() or a ) | Empty or unbalanced parentheses |
invoice AND | A trailing AND, OR or NOT |
- or "" | A term with no letters or digits has nothing to match |
after:someday | The date couldn’t be read |
Queries are limited to 200 words, operators and parentheses, and 30 levels of nested NOT and parentheses. Long runs of OR or AND count as one level.
Searching inside a thread
To find text in the open thread, use Edit > Find > Find in Thread (mod+F with the Gmail and Apple Mail sets), then Find Next and Find Previous.
Search from the CLI and agents
The airpost search command uses the same grammar and the same index. Quote the whole query so your shell keeps the inner quotes and parentheses:
airpost search 'from:alice "project alpha" after:2w'
airpost search 'has:attachment NOT (in:trash OR in:spam)' -n 20 --json
Thread actions take a query too, so you can act on everything a search finds. --dry-run lists what would change first:
airpost archive --query 'from:newsletter@example.com before:6m' --dry-run
airpost archive --query 'from:newsletter@example.com before:6m'
airpost undo
Without --limit, a query matching more than 500 threads is refused. AI agents use the same grammar through the MCP server’s search_mail tool; see Agents.
Search covers mail. Contacts have their own prefix search (airpost contacts <name>), and calendar events their own index. See Local features for what else runs on your machine.