How to Search Your Email with grep and ripgrep

Email services such as Gmail, Outlook, and iCloud keep messages on their servers. To search those messages with grep or ripgrep (rg), you first need email files on your computer. These command-line search tools look through local text files; they do not search a provider’s mailbox directly.

mailmd is the recommended way to create a local email copy for this kind of search. It saves each message as a Markdown file, which grep and rg can read. Once the files are on your computer, you can search message text and headers, narrow results with regular expressions, and see which file contains a match.

Search a local email archive #

A local archive gives command-line tools files to search. With mailmd, each message becomes a Markdown file. Its headers appear in a metadata section at the top, called frontmatter, and HTML email becomes readable Markdown. mailmd puts folders and years in directories, so a recursive search can include messages throughout the archive.

Use rg for a concise search across the archive:

rg -n -i -C 2 -F 'budget approval' ~/mail

Here, -n prints line numbers, -i ignores letter case, and -C 2 shows two surrounding lines. -F treats the search text as a literal phrase instead of a regular expression, a search pattern that uses special symbols to match text. The output includes the file path, so you can find the message to inspect.

GNU grep can search the same files recursively:

grep -Rni -C 2 -F -- 'budget approval' ~/mail

Both commands search one line at a time. They will not find a phrase as a whole if it splits across two lines. In that case, search for a distinctive word or a shorter phrase from the message. To search for either of two options, use a regular expression with rg:

rg -n -i 'invoice|receipt' ~/mail

GNU grep uses basic regular expressions by default. Add -E to use extended regular expressions, which allow patterns such as this either-or search. The -l option prints only matching filenames, and -c counts matching lines. The GNU grep options include these and other ways to change the output.

rg skips hidden files, ignored paths, and binary files by default. As a result, it can miss messages in hidden directories or paths covered by ignore rules. To include hidden and ignored paths in a mail search, add --hidden --no-ignore:

rg --hidden --no-ignore -n -i -F 'budget approval' ~/mail

The ripgrep user guide describes these defaults and other search options. Use the extra flags when the archive’s layout or ignore files would otherwise hide messages; keep the ordinary command when you want those exclusions.

Set up mailmd for searching #

mailmd is a free, open-source command-line tool that copies email into Markdown files on your computer. It works with IMAP mailboxes, and it connects to Gmail through the Gmail API and to Outlook.com through Microsoft Graph. These API connections require an OAuth app, a registered app that lets mailmd request account access. You create the app in Google Cloud or Microsoft Entra. Most Outlook mailboxes no longer accept passwords for IMAP connections.

On Linux, macOS, or Windows in Git Bash, install mailmd and connect the mailbox using the appropriate command:

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

# For an IMAP mailbox, including Gmail with an app password:
mailmd connect imap --email you@example.com

# For Gmail through the Gmail API:
mailmd connect gmail --client-secret client_secret.json

# For Outlook.com:
mailmd connect outlook --client-id <id>

mailmd sync

Choose one connection command for the mailbox. To connect through the Gmail API, you need the client secret file for your OAuth app. To connect to Outlook.com, you need the client ID from your Microsoft Entra app. Many IMAP providers require an app password; mailmd tells you when to use one. The first sync saves mail under ~/mail/<account>. By default, mailmd leaves out spam and trash. Gmail over IMAP syncs All Mail, including archived messages.

mailmd opens folders read-only and requests read access. It does not mark messages as read, move or delete mail, or send messages. A later sync adds new mail and updates whether messages are marked read or starred. If you stop a sync with Ctrl-C, mailmd keeps what it already saved and continues on the next run. It never deletes files from the archive; messages later deleted from the server remain on disk and are marked as deleted on the server.

After the sync, run rg or grep against the archive as shown above. mailmd has no built-in search engine, so these tools search the Markdown files directly. For recurring searches, the mailmd project documents the tool and its options. You can also schedule mailmd sync --quiet with cron, systemd, launchd, or Task Scheduler to keep the local copy current.

The archive contains readable email, so protect it like the mailbox itself. mailmd stores login details outside the archive without encryption. Only your user can read them. If a coding agent reads the archive, the agent sends the content it reads to its model provider. You enter your password into mailmd yourself, so the agent does not see it.

When grep is not enough #

grep and rg work well when messages already exist as text files. Older archives may instead use mbox, a format that stores multiple messages in one file, or Maildir, a format that stores messages as separate files in folders. Raw email can also store parts of a message in encoded form. The stored text can then differ from the words you see in an email reader, so a search for those words might not match.

For mbox files, grepmail is a specialized option: it searches headers and bodies and accepts Perl regular expressions. Its documented support is for traditional UNIX mbox files, and its manual lists limitations in date parsing and patterns containing $. Check the results carefully when your search depends on those patterns or date filters. For a Markdown archive, rg or grep searches the individual message files directly.