Search workflow
Core idea
Section titled “Core idea”mxr treats search as navigation, not a bolt-on filter. Search results drive the TUI mail list, saved searches, exports, and batch mutations.
Ask Archive for a receipt or a reference
Section titled “Ask Archive for a receipt or a reference”Search returns emails. When what you want is a fact from a receipt, order or booking (a booking reference, what you paid, the invoice PDF), ask Archive instead: it answers with the field from the record, one row per order rather than one per email, and searches all mail only when no record matches.
mxr records ask "dell receipt"What a search matches
Section titled “What a search matches”A search matches the words in a message’s text. HTML markup, styles and scripts
are not indexed. Quoted replies and signatures are searchable, so a phrase you
only find inside an earlier message in the thread still matches.
has:youtube, has:link and the other has: filters still read the raw
message, so they keep finding links inside HTML.
After you upgrade, the first start rebuilds the search index once, from the local
store, because the indexed text changed. Until the rebuild finishes, search
answers from a limited local search, and the result says so. If that rebuild
fails, search stays limited and says the last rebuild failed. Run
mxr doctor --reindex or restart the daemon to retry.
Common patterns
Section titled “Common patterns”mxr search "from:alice@example.com unread"mxr search "label:work has:attachment"mxr search "subject:\"quarterly review\" after:2026-01-01"mxr search "unsubscribe"mxr search "label:inbox" --format idsmxr search "adrian in:inbox" --limit 1000mxr search "{from:amy@example.com from:david@example.com} subject:(dinner movie)"mxr search "holiday AROUND 10 vacation"mxr search "body:house of cards" --mode hybrid --explainmxr search "is:owed-reply"mxr search "has:calendar newer_than:30d"mxr search "is:unread" --account workThe is: filter has the usual suspects (unread, read, starred,
draft, sent, trash, spam, answered, inbox, archived,
reply-later) and one computed lens worth knowing about:
is:owed-reply(aliasis:owed) — threads where the latest message is inbound, no later outbound exists, the sender isn’t a newsletter/list, and the screener hasn’t denied them. Same result set asmxr owed --all, so the TUI sidebar can show it as a saved search.mxr owedwithout--allnarrows it to the desk’s You owe lane: people you have written to, mail still in the inbox.
Gmail-style operators are parsed by the mail-query crate, then executed
against mxr’s local index. The important practical consequence: syntax
parity is separate from storage parity. For example, Gmail’s color-star
operators parse, but mxr currently stores starred as a boolean, so
has:yellow-star and has:purple-question both mean “starred” locally.
+word matches the word exactly, case-insensitively, and never its
inflections: +running finds “running” but not “run” or “runs”. Plain words
already behave this way, because the text fields are not stemmed, so +word
only matters once a stemmed field exists. Rules use the same whole-word
meaning for +word; see Rules.
The same gap applies to address operators, and it bites harder because the
query still parses and simply returns nothing: from:, to:, cc:, bcc:
and deliveredto: are indexed as whole addresses, so from:alice and
from:github.com match nothing where Gmail would match on the local part or
the domain. Pass the whole address (from:alice@example.com).
Search modes
Section titled “Search modes”lexical: exact BM25/Tantivy retrievalhybrid: lexical + dense retrieval + RRFsemantic: dense retrieval only
Semantic search is optional. It is an mxr-platform feature layered on top of the mail runtime, not a requirement for normal mail sync/read/send.
Embeddings stay local. OCR is not used for semantic indexing.
Account-scoped search
Section titled “Account-scoped search”mxr search "from:notifications@github.com is:unread" --account work --format jsonmxr search "subject:invoice newer_than:30d" --account billing@example.com --format idsmxr count "has:calendar" --account personalWhat you get: search and count results limited to the selected account.
By default, mxr search searches all enabled accounts. Add
--account <selector> when you want one account only.
Selectors accept account key, email address, account id, or an unambiguous display name. Unknown or ambiguous selectors fail before the search runs.
Without --limit or --sort, mxr search uses the [search] settings in your config: max_results is the page size and default_sort the order. Explicit flags win. The daemon reads these settings at startup, so run mxr restart after changing them.
Account filtering happens before pagination and applies to lexical,
hybrid, and semantic modes. That means --limit 50 --account work
returns up to 50 work-account hits, not “50 global hits, then filter to
work”.
mxr search "from:notifications@github.com is:unread" --account work --limit 50 --format jsonDedicated search page
Section titled “Dedicated search page”The TUI has two distinct search tools:
/from Mailbox opens Search and hits the full local indexCtrl-ffrom Mailbox filters only the current mailbox view
The Search page gives you:
- Query input
- Result list
- Preview pane
- Lexical / hybrid / semantic modes
- Normal open flow into mailbox/thread interaction once a result is previewed
Useful combinations
Section titled “Useful combinations”- Use
mxr search ... --format ids | xargs ...for shell pipelines. - Add
--account <selector>to keep a query, saved-search run, export, or mutation inside one account. - Save high-value searches in the TUI sidebar for recurring workflows.
- Use
mxr count QUERYfor quick status-bar or script integration. - Use
mxr export --search QUERY --format mboxto archive slices of mail. - Use
--explainwhen debugging hybrid/semantic fallback or dense contribution.
Fielded hybrid behavior
Section titled “Fielded hybrid behavior”Examples:
mxr search "body:house of cards" --mode hybrid --explainmxr search "subject:house of cards" --mode hybrid --explainmxr search "filename:house of cards" --mode hybrid --explainCurrent intent:
- lexical side stays literal and field-aware
- dense side respects chunk source kinds
body:searches body chunkssubject:searches header chunksfilename:searches attachment-origin chunks
Literal lexical matches should usually remain stronger than merely related semantic matches.
When search is fresh
Section titled “When search is fresh”- lexical search is fresh right after the sync batch commits
- hybrid search can use lexical results immediately, even if semantic retrieval is disabled
- semantic-only readiness depends on the active profile being built
Check semantic readiness with:
mxr semantic statusmxr doctor --semantic-statusWhen the index is unavailable
Section titled “When the index is unavailable”If the search index is down (the daemon’s index worker has stopped, or the index is being rebuilt), mxr search, the TUI and the web app still answer plain words, subject: and from: from your local database. They say so:
Search is limited while the index is unavailable: subject, sender and preview only. Restart the daemon or run `mxr doctor --reindex`.On the command line the line goes to stderr, so piped results are unchanged, and --format json adds a degraded field. Limited results are newest first and do not look inside message bodies. Words match the subject, the sender’s name and the preview; from: matches the whole address; in:anywhere still works and includes Trash and Spam.
A query that uses anything else (is:, has:, label:, dates, to:, OR, -term) is refused with the same message, naming the part that cannot run, instead of returning a looser answer. Counts, grouping and --search selections for archive, label and other changes are refused too. Restart the daemon (mxr restart) and full search comes back.
TUI flow
Section titled “TUI flow”- Press
/in Mailbox to jump into Search. - Start typing. The Search page runs live after a short debounce.
- Press
Enterto run immediately when you do not want to wait for debounce. - Use
Tabto change lexical / hybrid / semantic mode while editing, or to switch results and preview when not editing. - Use
j/kto move the result cursor. - Use
Enter,o, orlto open the selected result in preview. - Use
Escto move preview -> results -> mailbox.
Search is full-corpus by design. It searches beyond the currently loaded mailbox slice.
Saved searches
Section titled “Saved searches”Saved searches are not a secondary convenience. They are persistent inbox lenses and appear in:
- The sidebar
- Command palette
- CLI via
mxr saved
Common flow:
mxr saved add urgent "label:inbox unread from:boss@example.com"mxr saved listmxr saved run urgentIn real life
Section titled “In real life”- Quick “did I miss anything important today”:
mxr search 'is:unread label:inbox newer_than:1d' --format json | jq '.results | group_by(.from) | map({sender: .[0].from, count: length})' - Find that one PDF you were sent last quarter:
mxr search 'has:attachment filename:pricing.pdf older_than:90d' --mode hybrid - Bulk-archive every receipt 30 days old:
mxr search 'label:receipts older_than:30d' --format ids | mxr archive --yes - Build a digest before a 1:1:
mxr search 'from:sarah@example.com newer_than:7d' --format json | jq -r '.results[].subject' - Pull only real conversations, hide newsletters:
mxr search 'is:unread has:link-none'— strips link-heavy promotional/transactional mail in one filter. - Triage the newsletter pile in bulk:
mxr search 'has:link-heavy older_than:7d' --format ids | mxr archive --yes— auto-archives newsletter-shaped mail older than a week. - Find a shared doc someone sent you:
mxr search 'from:alice@example.com has:link newer_than:14d'—has:linkexcludes trackers/unsubscribe URLs, so it surfaces real link-bearing replies. - Work the owed-reply backlog:
mxr search 'is:owed-reply' --format ids | mxr remind --when 'friday 16:00'— pin a Friday-afternoon nudge on every thread you owe a reply on. - Owed within the last two weeks only:
mxr search 'is:owed-reply newer_than:14d'— skip ancient threads you’ve implicitly already ignored. - Review recent meeting invites:
mxr search 'has:calendar newer_than:30d' --format ids | xargs -I{} mxr invite show {}— inspect invite details before deciding whether to RSVP.
Agent prompts that work
Section titled “Agent prompts that work”"Find every email mentioning 'launch checklist' since last Monday andsummarise what's still open. Use `mxr search 'launch checklistnewer_than:7d' --format json` and `mxr summarize` for any thread with4+ messages.""What did Bob email me about pricing in Q1? Use hybrid search and`--explain` so I can see why each result matched: `mxr search'from:bob@example.com pricing after:2026-01-01 before:2026-04-01' --mode hybrid--explain`."See also
Section titled “See also”- Labels and saved searches
- Semantic search
- Archive: the answer box over records
- Recipes — fzf / jq
- CLI —
mxr search
Search results in the web app
Section titled “Search results in the web app”The results page is titled with your query and counts what its rows are
(“4 conversations”). Exact, Hybrid and Meaning sit under the box. Show, Sort,
Account and the sender, list or category chips are behind Filters (g f).
The chips show a count only when the rows are messages, since the counts are
messages.
Sort starts at Default, which uses default_sort from your config. Picking
Best match, Newest or Oldest overrides it; choosing Default again goes back to
the config. Page size comes from max_results in the same way.