lieer: Syncing Gmail with notmuch

If you want to search Gmail from a local email archive, Lieer connects a Gmail account to notmuch, a tool that indexes email stored on your computer so you can search and tag it. Lieer downloads messages and Gmail labels into a local Maildir, a folder-based format for storing individual email messages. It also sends eligible notmuch tag changes back to Gmail.

Use Lieer when you want Gmail and a local notmuch archive to share label changes. It does not synchronize message deletions or add new messages to Gmail. For a different goal, mailmd is a free, open-source command-line tool that copies email into Markdown files you can read and search on your computer.

How Lieer connects Gmail and notmuch #

Lieer uses Gmail’s API to fetch messages and labels. In notmuch, Gmail labels appear as tags: short labels attached to messages that you can use to organize and search your archive. For example, a Gmail label named receipts becomes a notmuch tag that you can search locally.

Lieer transfers Gmail messages and labels into the local Maildir and synchronizes tag changes. Notmuch indexes the local messages and lets you search and manage their tags. The Lieer project documentation lists Python 3, notmuch 0.30 or later with its Python bindings, and Google API libraries as requirements.

Lieer’s gmi sync command pushes local tag changes and then pulls remote changes. You can also run gmi pull and gmi push separately. A pull can overwrite local tag changes on messages affected by remote updates. A push skips conflicts by default; gmi push -f forces local changes over remote changes, so use it only when that overwrite is intended.

Set up a local Gmail archive #

Lieer’s setup assumes that notmuch already has a configured mail folder and database. The notmuch database indexes messages in that folder, and its notmuch new command scans subdirectories to find and index new mail. The notmuch manual describes this scan and notes that the first index can take a long time for a large archive.

After setting up notmuch, create a directory for Lieer inside the mail folder and initialize it with gmi init. Lieer opens a browser to request access to Gmail, then stores an access token in the local repository. The default OAuth credentials are shared by Lieer users; the project documentation also explains how to create personal credentials in Google Cloud and pass them to gmi auth -c.

Once setup is complete, run gmi pull to fetch Gmail messages and labels. Run gmi sync to exchange label changes in both directions. If a pull stalls while fetching metadata, the documentation describes gmi pull --resume; it also warns that local changes made during the interruption can be ignored in a later push.

Understand what does and does not sync #

Lieer synchronizes message labels. It does not sync every mailbox action. Its documentation says it does not add or delete messages in Gmail, with trash and spam handled as synchronized labels. Deleting a local message therefore does not delete the Gmail message. To remove mail from Gmail, delete it there.

Draft and sent labels flow from Gmail to notmuch but do not sync back. Gmail’s Personal and Promotions category labels are ignored by default, and Lieer’s documentation says muted messages do not sync through the Gmail API. Lieer also excludes several local tags from remote synchronization by default.

Avoid changing synchronization settings casually after the first import. The documentation warns that changing ignored tags can alter tags or duplicate local files. Changes to filename extensions or other settings can cause the same problems. Try a dry run before a full pull or push, especially when changing ignored-tag settings. Lieer can overwrite remote changes when you force a push, or local changes when you force a pull.

When mailmd is a better fit #

Choose mailmd when you want a readable local email archive, rather than two-way tag synchronization between Gmail and notmuch. mailmd saves each message as a Markdown file, with its headers in a frontmatter section at the start of the file. It stores attachments beside the message and organizes folders and years in directories. It can also save the original .eml file.

mailmd connects to IMAP mailboxes and uses the Gmail API for Gmail. It uses Microsoft Graph for Outlook.com and related Microsoft services, which require an OAuth app in Google Cloud or Microsoft Entra for those API connections. mailmd reads mail without marking it as read. It never changes or moves messages in the mailbox, and it never deletes or sends them. Its sync adds new messages and updates read and starred marks in the archive; it never deletes archived files.

mailmd has no built-in search engine. You can search its files with tools such as rg or grep, filter its index.jsonl file with jq, or open the archive in an editor or note app. It can also keep a local copy when a message is later deleted from the server. Try mailmd if Markdown files and a read-only archive fit your needs better than notmuch’s searchable database and label synchronization. Its source code is available under the MIT license.

$ 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.