Search mail
mail_searchSearch a notmuch email database and return paged summaries of conversations or individual messages. Filter by query terms like sender, subject, and date ranges; choose granularity, sort order, and response format.
Instructions
Search notmuch and return a paged summary, at thread or message granularity.
Use granularity="threads" for "what conversations are there about Y": each row is one thread, dated by its newest (or oldest) matched message, with an authors column that can mix matched and unmatched participants (see the legend in the output). Use granularity="messages" for "the last mail from X" or "how many mails did X write": each row is one matching message with its own date, from and subject.
Do not use this to fetch full bodies (use mail_read_message / mail_read_thread) or to turn a person's name into addresses first (use mail_list_addresses; from: also matches notification mail that merely mentions the name).
Args:
query: A notmuch query, e.g. 'from:alice subject:invoice'. See
notmuch-search-terms(7) for the full syntax, including
'date:this_year..', 'date:last_month..', 'date:1Y..' and
'date:2026-01-01..2026-06-30' for date ranges.
scope: Name of a configured scope to AND with query (see
mail_list_scopes). Defaults to the configured default scope.
limit: Maximum number of rows to return. Omit for all results (the
default); set it only to cap the number returned, and when it
truncates the total is still reported.
offset: Number of matching rows to skip, for paging through
results already seen.
response_format: 'concise' (one line per row) or 'detailed' (adds
message counts/tags for threads, or the message_id for messages).
granularity: 'threads' (one row per conversation) or 'messages'
(one row per matching message).
sort: 'newest-first' or 'oldest-first'.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | newest-first | |
| limit | No | ||
| query | Yes | ||
| scope | No | ||
| offset | No | ||
| granularity | No | threads | |
| response_format | No | concise |