notmuch/

Notmuch logo

Tips and Tricks for using notmuch with Emacs

  1. Tips and Tricks for using notmuch with Emacs
    1. Setup
    2. Navigating & reading mails
    3. Sending mail
    4. Attaching files
  2. Advanced tips and tweaks
    1. Use separate emacs lisp file for notmuch configuration
    2. Add a key binding to add/remove/toggle a tag
    3. Restore reply-to-all key binding to 'r'
    4. How to do FCC/BCC...
    5. How to customize notmuch-saved-searches
    6. Viewing HTML messages with an external viewer
    7. msmtp, message mode and multiple accounts
    8. Address completion when composing
    9. How to sign/encrypt messages with gpg

The main Notmuch message reading client is notmuch.el, which is an emacs major mode, and is included in the notmuch package.

Setup

To use the Notmuch emacs mode, first add the following line to your .emacs rc file:

    (require 'notmuch)

or you can load the package via autoload:

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

Then, either run "emacs -f notmuch", or execute the command M-x notmuch from within a running emacs.

Navigating & reading mails

When first starting notmuch in emacs, you will be presented with the notmuch "hello" page. 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.

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 [ "$1" ]; do
        fullpath=$(readlink --canonicalize "$1")
        attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
        shift
    done
    emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"

Advanced tips and tweaks

Use separate emacs lisp file for notmuch configuration

Instead of adding notmuch configuration code to .emacs, there is an option to collect those to a separate file (which is only loaded when notmuch is invoked). To do this, write, for example a file called ~/.emacs.d/my-notmuch.el:

    ;; my-notmuch.el -- my notmuch mail configuration
    ;;

    ;; add here stuff required to be configured *before*
    ;; notmuch is loaded;

    ; uncomment and modify in case some elisp files are not found in load-path
    ; (add-to-list 'load-path "~/vc/ext/notmuch/emacs")

    ;; load notmuch 
    (require 'notmuch)

    ;; add here stuff required to be configured *after*
    ;; notmuch is loaded;

    ;(setq user-mail-address (notmuch-user-primary-email)
    ;      user-full-name (notmuch-user-name))

    ; uncomment & modify if you want to use external smtp server to send mail
    ; (setq smtpmail-smtp-server "smtp.server.tld"
    ;       message-send-mail-function 'message-smtpmail-send-it)

Then, adto .emacs:

    (autoload 'notmuch "~/.emacs.d/my-notmuch" "notmuch mail" t)

Add a key binding to add/remove/toggle a tag

The notmuch-{search,show}-{add,remove}-tag functions are very useful for making quick tag key bindings. For instance, here's an example of how to make a key binding to add the "spam" tag and remove the "inbox" tag in notmuch-show-mode:

In notmuch versions up to 0.11.x

    (define-key notmuch-show-mode-map "S"
      (lambda ()
        "mark message as spam"
        (interactive)
        (notmuch-show-add-tag "spam")
        (notmuch-show-remove-tag "inbox")))

Starting from notmuch 0.12 (not released yet) the functions notmuch-show-add-tag and notmuch-show-remove-tag have changed to be more versatile and lost noninteractive use. When upgrading to 0.12 the above needs to be changed to this:

    (define-key notmuch-show-mode-map "S"
      (lambda ()
        "mark message as spam"
        (interactive)
        (notmuch-show-tag-message "+spam" "-inbox")))

You can do the same for threads in notmuch-search-mode by just replacing "show" with "search" in the called functions.

(Starting from notmuch 0.12 use notmuch-search-tag-thread instead)

The definition above makes use of a lambda function, but you could also define a separate function first:

    (defun notmuch-show-tag-spam()
      "mark message as spam"
      (interactive)
      (notmuch-show-add-tag "spam")
      (notmuch-show-remove-tag "inbox")))
    (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)

(See above for analogy how to apply this for notmuch 0.12 and later)

Here's a more complicated example of how to add a toggle "deleted" key:

    (define-key notmuch-show-mode-map "d"
      (lambda ()
        "toggle deleted tag for message"
        (interactive)
        (if (member "deleted" (notmuch-show-get-tags))
            (notmuch-show-remove-tag "deleted")
          (notmuch-show-add-tag "deleted"))))

And version for notmuch 0.12 (not released yet)

    (define-key notmuch-show-mode-map "d"
      (lambda ()
        "toggle deleted tag for message"
        (interactive)
        (notmuch-show-tag-message
          (if (member "deleted" (notmuch-show-get-tags))
              "-deleted" "+deleted"))))

Restore reply-to-all key binding to 'r'

Starting from notmuch 0.12 the 'r' key is bound to reply-to-sender instead of reply-to-all. Here's how to swap the reply to sender/all bindings in show mode:

    (define-key notmuch-show-mode-map "r" 'notmuch-show-reply)
    (define-key notmuch-show-mode-map "R" 'notmuch-show-reply-sender)

And in search mode:

    (define-key notmuch-search-mode-map "r" 'notmuch-search-reply-to-thread)
    (define-key notmuch-search-mode-map "R" 'notmuch-search-reply-to-thread-sender)

How to do FCC/BCC...

The Emacs interface to notmuch will automatically add an Fcc header to your outgoing mail so that any messages you send will also be saved in your mail store. You can control where this copy of the message is saved by setting the variables message-directory (which defines a base directory) and notmuch-fcc-dirs which defines the subdirectory relative to message-directory in which to save the mail. Enter a directory (without the maildir /cur ending which will be appended automatically). To customize both variables at the same time, use the fancy command:

    M-x customize-apropos<RET>\(notmuch-fcc-dirs\)\|\(message-directory\)

This mechanism also allows you to select different folders to be used for the outgoing mail depending on your selected From address. Please see the documentation for the variable notmuch-fcc-dirs in the customization window for how to arrange this.

How to customize notmuch-saved-searches

When starting notmuch, a list of saved searches and message counts is displayed, replacing the older notmuch-folders command. The set of saved searches displayed can be modified directly from the notmuch interface (using the [save] button next to a previous search) or by customising the variable notmuch-saved-searches.

An example setting might be:

    (setq notmuch-saved-searches '(("inbox" . "tag:inbox")
                    ("unread" . "tag:inbox AND tag:unread")
                    ("notmuch" . "tag:inbox AND to:notmuchmail.org")))

Of course, you can have any number of saved searches, each configured with any supported search terms (see "notmuch help search-terms").

Some users find it useful to add and not tag:delete to those searches, as they use the delete tag to mark messages as deleted. This causes messages that are marked as deleted to be removed from the commonly used views of messages. Use whatever seems most useful to you.

Viewing HTML messages with an external viewer

The emacs client can display an HTML message inline using either the html2text library or some text browser, like w3m or lynx. This is controlled by the mm-text-html-renderer variable.

The first option is theorically better, because it can generate strings formatted for emacs and do whatever you want, e.g., substitute text inside <b> tags for bold text in the buffer. The library, however is still in a very early development phase and cannot yet process properly many elements, like tables and directives, and even the generated text is often poorly formatted.

Among the available browsers, w3m seems to do a better job converting the html, and if you have the w3m emacs package, you can use it, instead of the w3m-standalone, and thus preserve the text formatting.

But if the rendering fails for one reason or another, or if you really need to see the graphical presentation of the HTML message, it can be useful to display the message in an external viewer, such as a web browser. Here's a little script that Keith Packard wrote, which he calls view-html:

    #!/bin/sh
    dir=`mktemp -d`
    trap "rm -r $dir" 0
    cat "$@" > "$dir"/msg
    if munpack -C "$dir" -t < "$dir"/msg 2>&1 | grep 'Did not find'; then
        sed -n '/[Hh][Tt][Mm][Ll]/,$p' "$dir"/msg > $dir/part1.html
        rm "$dir"/msg
    fi
    for i in "$dir"/part*; do
        if grep -q -i -e '<html>' -e 'text/html' "$i"; then
            iceweasel "$i" &
            sleep 3
            exit 0
        fi
    done

Save that script somewhere in your ${PATH}, make it executable, and change the invocation of iceweasel to any other HTML viewer if necessary. Then within the emacs client, press '|' to pipe the current message, then type "view-html".

Keith mentions the following caveat, "Note that if iceweasel isn't already running, it seems to shut down when the script exits. I don't know why."

msmtp, message mode and multiple accounts

As an alternative to running a mail server such as sendmail or postfix just to send email, it is possible to use msmtp. This small application will look like /usr/bin/sendmail to a MUA such as emacs message mode, but will just forward the email to an external SMTP server. It's fairly easy to set up and it supports several accounts for using different SMTP servers. The msmtp pages have several examples.

A typical scenario is that you want to use the company SMTP server for email coming from your company email address, and your personal server for personal email. If msmtp is passed the envelope address on the command line (the -f/--from option) it will automatically pick the matching account. The only trick here seems to be getting emacs to actually pass the envelope from. There are a number of overlapping configuration variables that control this, and it's a little confusion, but setting these three works for me:

With that in place, you need a .msmtprc with the accounts configured for the domains you want to send out using specific SMTP servers and the rest will go to the default account.

If you have a hard time getting the above to work for you, as I did, it's also possible to add a message-send-mail-hook in your .emacs to send the from header explicitly as an argument to msmtp as described here on the emacswiki.

Address completion when composing

There are currently three solutions to this:

bbdb

bbdb is a contact database for emacs that works quite nicely together with message mode, including address autocompletion.

notmuch database as an address book

You can also use the notmuch database as a mail address book itself. To do this you need a command line tool that outputs likely address candidates based on a search string. There are currently three available:

You can perform tab-completion using any of these programs. Just add the following to your .emacs:

    (require 'notmuch-address)
    (setq notmuch-address-command "/path/to/address_fetching_program")
    (notmuch-address-message-insinuate)

Google Contacts

GooBook is a command-line tool for accessing Google Contacts. Install and set it up according to its documentation.

To use GooBook with notmuch, use this wrapper script and set it up like the programs above.

    #!/bin/sh
    goobook query "$*" | sed 's/\(.*\)\t\(.*\)\t.*/\2 \<\1\>/' | sed '/^$/d'

You can add the sender of a message to Google Contacts by piping the message (notmuch-show-pipe-message) to goobook add.

How to sign/encrypt messages with gpg

Messages can by signed using gpg by invoking M-x mml-secure-sign-pgpmime (or M-x mml-secure-encrypt-pgpmime). These functions are available via the standard message-mode keybindings C-c C-m s p and C-c C-m c p. To sign outgoing mail by default, use the message-setup-hook in your .emacs file:

    ;; Sign messages by default.
    (add-hook 'message-setup-hook 'mml-secure-sign-pgpmime)

This inserts the required <#part sign=pgpmime> into the beginning of the mail text body and will be converted into a pgp signature when sending (so one can just manually delete that line if signing is not required).

Alternatively, you may prefer to use mml-secure-message-sign-pgpmime instead of mml-secure-sign-pgpmime to sign the whole message instead of just one part.

Troubleshooting message-mode gpg support