Skip to content

Search workflow

mxr treats search as navigation, not a bolt-on filter. Search results drive the TUI mail list, saved searches, exports, and batch mutations.

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.

Terminal window
mxr records ask "dell receipt"

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.

Terminal window
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 ids
mxr search "adrian in:inbox" --limit 1000
mxr 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 --explain
mxr search "is:owed-reply"
mxr search "has:calendar newer_than:30d"
mxr search "is:unread" --account work

The 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 (alias is: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 as mxr owed --all, so the TUI sidebar can show it as a saved search. mxr owed without --all narrows 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).

  • lexical: exact BM25/Tantivy retrieval
  • hybrid: lexical + dense retrieval + RRF
  • semantic: 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.

Terminal window
mxr search "from:notifications@github.com is:unread" --account work --format json
mxr search "subject:invoice newer_than:30d" --account billing@example.com --format ids
mxr count "has:calendar" --account personal

What 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”.

Terminal window
mxr search "from:notifications@github.com is:unread" --account work --limit 50 --format json

The TUI has two distinct search tools:

  • / from Mailbox opens Search and hits the full local index
  • Ctrl-f from 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
  • 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 QUERY for quick status-bar or script integration.
  • Use mxr export --search QUERY --format mbox to archive slices of mail.
  • Use --explain when debugging hybrid/semantic fallback or dense contribution.

Examples:

Terminal window
mxr search "body:house of cards" --mode hybrid --explain
mxr search "subject:house of cards" --mode hybrid --explain
mxr search "filename:house of cards" --mode hybrid --explain

Current intent:

  • lexical side stays literal and field-aware
  • dense side respects chunk source kinds
  • body: searches body chunks
  • subject: searches header chunks
  • filename: searches attachment-origin chunks

Literal lexical matches should usually remain stronger than merely related semantic matches.

  • 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:

Terminal window
mxr semantic status
mxr doctor --semantic-status

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.

  1. Press / in Mailbox to jump into Search.
  2. Start typing. The Search page runs live after a short debounce.
  3. Press Enter to run immediately when you do not want to wait for debounce.
  4. Use Tab to change lexical / hybrid / semantic mode while editing, or to switch results and preview when not editing.
  5. Use j / k to move the result cursor.
  6. Use Enter, o, or l to open the selected result in preview.
  7. Use Esc to move preview -> results -> mailbox.

Search is full-corpus by design. It searches beyond the currently loaded mailbox slice.

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:

Terminal window
mxr saved add urgent "label:inbox unread from:boss@example.com"
mxr saved list
mxr saved run urgent
  • 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:link excludes 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.
"Find every email mentioning 'launch checklist' since last Monday and
summarise what's still open. Use `mxr search 'launch checklist
newer_than:7d' --format json` and `mxr summarize` for any thread with
4+ 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`."

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.