Airpost
Using Airpost

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

OperatorMatchesExample
from:Sender name or addressfrom:alice
to:Any recipient: To, Cc or Bcc, by name or addressto:team@example.com
subject:Words in the subjectsubject:invoice
in:A folder or label: inbox, sent, archive, trash, spam, drafts, or a folder or label namein:inbox, in:receipts
is:unread / is:readRead stateis:unread
is:starred / is:unstarredStarred stateis:starred
has:attachmentThreads 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

SyntaxMeaningExample
a b or a AND bBothfrom:alice has:attachment
a OR bEitherfrom:alice OR from:bob
a NOT ba but not binvoice NOT in:trash
( )Groupingsubject:"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:

FormExamples
ISO dates2024-03-01, 2024/3/1, 2024.03.01
A month2024-03, march, march 2024 (the 1st of the month)
Month and daymar 1, 1 mar, "march 1st, 2024", "1 march 2024"
Weekdaysmonday, mon, tues
Relativetoday, 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:

QueryWhy
is:importantis: only takes read, unread, starred or unstarred
has:pdfhas: only takes attachment or attachments
from:An operator needs a value
() or a )Empty or unbalanced parentheses
invoice ANDA trailing AND, OR or NOT
- or ""A term with no letters or digits has nothing to match
after:somedayThe 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.