notmuch: Fast Search and Tagging for Mail on Your Disk

If your email is stored as files on your computer, notmuch can build an index, a searchable catalog of those files, so you can search and tag messages from the command line. It groups related messages into conversations called threads, then returns results you can use in a mail client or scripts. notmuch searches mail stored on your computer; a separate tool typically downloads or synchronizes messages from your mailbox.

For a different approach, mailmd is a free, open source command-line tool that copies email into Markdown files on your computer, one file per message. notmuch suits people who want a searchable local mail store with tags and a choice of interfaces. mailmd suits people who want readable files they can search with ordinary tools.

How notmuch searches local mail #

notmuch indexes messages stored as individual files, commonly in a Maildir archive. A Maildir stores each message in its own file and uses folders and file names to show how the mail is organized and its state. The older notmuch manual says mbox archives, where one file contains many messages, need conversion before notmuch can use them.

A typical setup uses a separate mail-sync tool, such as mbsync, to copy mail onto the computer. Then notmuch new scans the mail directory for new messages and updates the index. notmuch also provides notmuch insert, which adds a delivered message to the index. The distinction matters: notmuch searches mail already on disk; it does not fetch mail from an IMAP server, which lets mail programs access a remote mailbox. A discussion of scanning for new messages describes these two ways to add mail to the index.

Run notmuch search to search the indexed collection. For example, notmuch search 'tag:inbox' looks for messages tagged inbox. By default, the command presents one line per thread, including the thread ID and a date. Each line also gives match and message counts, participants, and the subject. Results sort newest first. The notmuch 0.40 search documentation describes JSON and plain-text output, as well as S-expression, a data format that uses nested parentheses. It lists output modes for summaries, threads, messages, files, and tags.

Thread-level results help when a conversation contains several messages: a search can show the matching messages and the total messages in that thread. When a script needs individual message files, choose the files output mode and handle duplicates carefully. A message can have more than one filename, and searches using folder: or path: can return duplicate filenames from other directories.

Tags organize mail without relying on folders #

notmuch lets you attach tags such as work, receipts, or follow-up to messages, then search by those tags. A message can have more than one tag, so you can group the same mail in several ways without moving it between folders. You can also save a search in a mail interface and revisit it to see the messages that match now, instead of maintaining a separate folder for every category.

Tagging operates on notmuch’s local view of mail. When a mail program accesses a mailbox through IMAP, do not assume that adding or removing a notmuch tag changes a label on the server. A 2024 discussion of notmuch and mail synchronization notes that tags are not transferred back to the IMAP host in the setup being discussed; server-side deletion behavior also depends on the mbsync configuration.

The search command can exclude messages with configured tags unless the query asks for them. For example, you can configure tags for mail you want left out of ordinary results. The search documentation explains how search.exclude_tags and the --exclude option change which messages match.

Choose a mail interface that fits your setup #

notmuch is a search and tagging tool, not a complete mail client. Some people use its Emacs interface; others connect it to separate interfaces. A notmuch mailing-list reply names Bower, Neomutt, and Alot among interfaces used alongside editors such as Neovim. You can also use command output in shell scripts or other programs.

The search command formats results for people and software. Use the default summary to review conversations in a terminal. Choose JSON or null-separated text when a script needs structured results. Null-separated text puts a null character between results and works with tools such as xargs -0. The documentation also describes notmuch dump and notmuch restore for saving and restoring tags, which helps preserve local organization separately from the message files.

When mailmd is a better fit #

Choose mailmd when you want a browsable archive of Markdown files instead of a mail index and client setup. Each message gets its own file, with its headers in a frontmatter block at the start of the file. mailmd turns HTML email into readable Markdown. It saves attachments next to the message and writes an index.jsonl file that scripts can filter. It has no built-in search engine, so you search the files with tools such as rg or grep, or filter the index with jq.

mailmd reads mail without changing the mailbox: it opens folders read-only and requests read access. It never marks, moves, deletes, or sends messages. It leaves archived files in place even if the corresponding server message is later deleted. Spam and trash stay out unless requested. For Gmail over IMAP, mailmd syncs All Mail, which includes archived messages.

The tool supports IMAP mailboxes. It connects to Gmail through the Gmail API and to Outlook mail through Microsoft Graph, services that let programs access those mailboxes. These connections require an OAuth app, a registration that grants the tool access, which you create in Google Cloud or Microsoft Entra. You can run mailmd sync again to add new mail and update read and starred marks; interrupting it with Ctrl-C keeps files already saved, and the next run continues.

Try mailmd if you want email as ordinary local files. You can use those files with editors and scripts, keep them in backups, or give them to coding agents. Its GitHub repository provides setup instructions. mailmd does not act as a mail client or free mailbox storage on its own; you must delete messages from the mailbox yourself after keeping a copy if that is your goal.

$ curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh

Set up mailmd so you can read my email. Use https://github.com/vincentsch/mailmd: read its AGENTS.md and follow the steps. Connect my mailbox and run the first sync. Then show me where the files are.