[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
# Notmuch Emacs Interface

One of the more popular Notmuch message reading clients is **notmuch.el**, or
`notmuch-emacs`, an [Emacs](https://www.gnu.org/software/emacs/) major mode for
interacting with Notmuch. It is included in the Notmuch package (`notmuch-emacs`
in Debian). The [[screenshots|screenshots]] give a good overview of the mode.

This page is a basic guide for setting up and using Notmuch with Emacs. See also
the [[tips and tricks page|emacstips]] for more advanced details.

[[!toc levels=2]]

## Prerequisites

The Notmuch Emacs interface uses the Notmuch [[command line interface|manpages]]
to interact with the Notmuch database and your mail store. Please make sure
you've [[set up Notmuch|getting-started]] first.

## Installation

Due to the dependency on the command line interface, the Notmuch Emacs interface
version must be compatible with the Notmuch version. On Linux, the easiest way
to ensure this is to use the package(s) in your distribution's package
repository.

If you've installed Notmuch from a [git
checkout](https://git.notmuchmail.org/git/notmuch) or a [source
release](https://notmuchmail.org/releases/), Notmuch Emacs is included by
default.

It is **not** recommended to install Notmuch Emacs from the Emacs Lisp Package
Archive (ELPA), as the version there is likely not in sync with the command line
interface.

## Setup

First, you need to tell Emacs about Notmuch. Add this to your `.emacs` rc file:

        (autoload 'notmuch "notmuch" "notmuch mail" t)

or if you always want to load Notmuch when you start Emacs:

        (require 'notmuch)

To start Notmuch Emacs, either run `emacs -f notmuch`, or execute the command
`M-x notmuch RET` from within a running Emacs. This will bring you to the
Notmuch Hello view.

## Customization

Notmuch Emacs uses the Emacs customization interface extensively for
configuration. Execute `M-x customize-group RET notmuch RET` to get to the
Notmuch main customization group.

### <span id="notmuch_init_file"> Notmuch Emacs configuration file </span>

After Notmuch is loaded `notmuch-init-file` (typically
 `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists
it is loaded. Most Emacs lisp based configuration not suitable via
customization can be put there instead of `~/.emacs`.

## Navigating & reading mails

When first starting Notmuch in Emacs, you will be presented with the
Notmuch "hello" page.  If it exits with an error after writing
"Welcome to notmuch. You have" you need to do the basic Notmuch setup
first (see above).
From here you can do searches, see lists of recent
searches, saved searches, message tags, help information, etc.

Executing a search will open a new buffer in `notmuch-search-mode`
displaying the search results.  Each line in the search results
represents a message thread.  Hitting the '?' key will show help for
this mode.

In general, the 'q' will kill the current Notmuch buffer and return
you to the previous buffer (sort of like a 'pop').

In search mode, navigating to a thread and hitting return will then
open a new buffer in `notmuch-show-mode`, which will show the actual
message contents of the thread.

## Sending mail

In any Notmuch mode, you can start a new message by hitting the 'm'
key.  To reply to a message or thread, just hit the 'r' key.

When composing new messages, you will be entered in Emacs's
`message-mode`, which is a powerful mode for composing and sending
messages.  When in message mode, you can type `C-c ?` for help.

If you would like to use address autocompletion when composing
messages, see [address completion](emacstips#index13h2).

When you are ready to send a message, type `C-c C-c`. By default
message mode will use your sendmail command to send mail, so make sure
that works. One annoying standard configuration of message mode is
that it will hide the sent mail in your Emacs frame stack, but it will
not close it. If you type several mails in an Emacs session they will
accumulate and make switching between buffers more annoying. You can
avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
in your `.emacs` file
(or doing `M-x customize-variable<RET>message-kill-buffer-on-exit<RET>`)
which will really close the mail window after sending it.

## Attaching files

Using the `M-x mml-attach-file` command, you can attach any file to be
sent with your mail. By default this command is bound to the menu item
*Attachments--Attach File* with the key binding `C-c C-a`. The
variable `mml-dnd-attach-options` (`M-x
customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
allow the prompting for various attachment options (such as
inline/attachment) if you want to do that.

For those who prefer a more graphical interface, you can also simply
drag and drop files from a file manager into a mail composition window
to have them attached. In Ubuntu this works without any modifications
if files are dragged from the file manager.

And for those who prefer working from command line, the following
script opens new Emacs window with empty message and attaches files
mentioned as script arguments. (Note: The script expects that you have
`(server-start)` in your `.emacs` file.)

        #!/bin/sh
        attach_cmds=""
        while [ $# -gt 0 ]; do
            fullpath=$(readlink --canonicalize "$1")
            attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
            shift
        done
        emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"