Getting Started with Notmuch

This is a work in progress.

This is your friendly guide and tutorial to getting started with Notmuch. It will help you through the first steps of setting up Notmuch.

All Notmuch commands have manual pages. Please refer to them for details.

Prerequisites

In order to use Notmuch, you will need to have your email messages stored in your local filesystem, one message per file. For example, Maildir, Maildir++, and MH formats work like this, while mbox does not. Storing the messages one message per file is the only hard dependency for trying out Notmuch.

We will get back to delivering messages later, for now we'll just assume you already have messages in this format.

Installation

On Linux, the easiest way to install Notmuch is through your distribution's package repository. If you're installing Notmuch from a git checkout or a source release, please refer to the INSTALL document.

Configuration

To configure Notmuch, just run

    notmuch

This will interactively guide you through the setup process, and save the configuration to $HOME/.notmuch-config. If you'd like to change the configuration in the future, you can either edit that file directly, or run notmuch setup.

This step only modifies the configuration file.

Initial Indexing

Notmuch needs a search database to operate. The next step is to run

    notmuch new

to index all your messages in the search database. The database will be stored in .notmuch directory under your mail store. The database is not a replacement or storage for your messages; it's just an index to find the right message files.

Notmuch does not modify or delete your mails. This is one of the main design principles of Notmuch. (The only exception is renaming files upon tagging according to the Maildir specification if the maildir.synchronize_flags configuration option is set.) It should be safe to try Notmuch.

Depending on the amount of mail you have the initial indexing process can take a long time, so expect that. Also, the resulting database will require roughly the same amount of storage space as your current collection of email.

After this step, you can try out the Notmuch command line interface, or Notmuch Emacs interface.

Converting Existing mbox to Maildir

The mb2md tool can be used to convert existing mbox files to Maildir.

Beware that the source and destination directory options to mb2md are relative to the user's home directory, not relative to the current working directory.

Delivering New Messages

Notmuch itself does not receive messages. There is no IMAP or POP support. You will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to receive the messages.

There are two ways to deliver and index messages:

• Use an external tool (such as offlineimap or mbsync) to deliver the messages to your mail store, and run notmuch new to discover and index the newly delivered messages (and any other changes in the mail store).

• Use an external tool (such as fetchmail) receive the messages, and configure the tool to use notmuch insert as a Mail Delivery Agent to deliver the messages to your mail store and index them.

Automation Via Hooks

Notmuch supports running user defined hooks before or after certain commands. Hooks can be arbitrary executable programs or scripts. For example, if you always run your mail delivery tool first and notmuch new after that, you can run the tool from Notmuch pre-new hook, and simply run notmuch new to do both. If you always do some tagging after indexing of new messages, you may want to set up a post-new or post-insert hook to do that automatically.

Backing Up and Restoring the Database

The Notmuch database contains a search index of your messages, along with all the tags you've added to your messages. The search index can be regenerated by indexing the messages again, but the tags will be lost if the database is lost. (If you have maildir.synchronize_flags configuration option enabled, also some of the tags can be regenerated from maildir flags.)

To create a plain-text dump of the tags, run

    notmuch dump --output=dump.txt

To restore the tags from the dump, run

    notmuch restore --input=dump.txt

Removing Notmuch

Did not like it after all? All you need to do is remove the database and the configuration file. The database is stored in the .notmuch directory under your mail store. And your mail store is at notmuch config get database.path.

You may want to use the notmuch dump command to create a backup of any tags you've added before removing the database.