1 # Tips and Tricks for using notmuch with Emacs
3 One of the more popular notmuch message reading clients is
4 **notmuch.el**, an [emacs](http://www.gnu.org/software/emacs/) major
5 mode for interacting with notmuch. It is included in the notmuch
6 package. This page goes over some usage tips for using notmuch with
13 To use the Notmuch emacs mode, first add the following line to your
18 or you can load the package via autoload:
20 (autoload 'notmuch "notmuch" "notmuch mail" t)
22 Then, either run "emacs -f notmuch", or execute the command `M-x
23 notmuch` from within a running emacs.
25 ## Navigating & reading mails
27 When first starting notmuch in emacs, you will be presented with the
28 notmuch "hello" page. From here you can do searches, see lists of
29 recent searches, saved searches, message tags, help information, etc.
31 Executing a search will open a new buffer in `notmuch-search-mode`
32 displaying the search results. Each line in the search results
33 represents a message thread. Hitting the '?' key will show help for
36 In general, the 'q' will kill the current notmuch buffer and return
37 you to the previous buffer (sort of like a 'pop').
39 In search mode, navigating to a thread and hitting return will then
40 open a new buffer in `notmuch-show-mode`, which will show the actual
41 message contents of the thread.
45 In any notmuch mode, you can start a new message by hitting the 'm'
46 key. To reply to a message or thread, just hit the 'r' key.
48 When composing new messages, you will be entered in emacs's
49 `message-mode`, which is a powerful mode for composing and sending
50 messages. When in message mode, you can type `C-c ?` for help.
52 If you would like to use address autocompletion when composing
53 messages, see [address completion](#address_completion).
55 When you are ready to send a message, type `C-c C-c`. By default
56 message mode will use your sendmail command to send mail, so make sure
57 that works. One annoying standard configuration of message mode is
58 that it will hide the sent mail in your emacs frame stack, but it will
59 not close it. If you type several mails in an emacs session they will
60 accumulate and make switching between buffers more annoying. You can
61 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
62 in your `.emacs` file (or doing `M-x
63 customize-variable<RET>message-kill-buffer-on-exit<RET>`) which will
64 really close the mail window after sending it.
68 Using the `M-x mml-attach-file` command, you can attach any file to be
69 sent with your mail. By default this command is bound to the menu item
70 *Attachments--Attach File* with the key binding `C-c C-a`. The
71 variable `mml-dnd-attach-options` (`M-x
72 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
73 allow the prompting for various attachment options (such as
74 inline/attachment) if you want to do that.
76 For those who prefer a more graphical interface, you can also simply
77 drag and drop files from a file manager into a mail composition window
78 to have them attached. In Ubuntu this works without any modifications
79 if files are dragged from the file manager.
81 And for those who prefer working from command line, the following
82 script opens new emacs window with empty message and attaches files
83 mentioned as script arguments. (Note: The script expects that you have
84 `(server-start)` in your `.emacs` file.)
89 fullpath=$(readlink --canonicalize "$1")
90 attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
93 emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
95 ## Issues with Emacs 24
97 If notmuch-show-mode behaves badly for you in emacs 24.x try adding one of
99 (setq gnus-inhibit-images nil)
109 # Advanced tips and tweaks
111 ## Use separate emacs lisp file for notmuch configuration
113 Instead of adding notmuch configuration code to `.emacs`, there
114 is an option to collect those to a separate file (which is only
115 loaded when `notmuch` is invoked). To do this, write, for example
116 a file called `~/.emacs.d/my-notmuch.el`:
118 ;;; my-notmuch.el -- my notmuch mail configuration
121 ;;; add here stuff required to be configured *before*
122 ;;; notmuch is loaded;
124 ;; uncomment and modify in case some elisp files are not found in load-path
125 ;; (add-to-list 'load-path "~/vc/ext/notmuch/emacs")
130 ;;; add here stuff required to be configured *after*
131 ;;; notmuch is loaded;
133 ;; uncomment & modify if you want to use external smtp server to send mail
134 ;; (setq smtpmail-smtp-server "smtp.server.tld"
135 ;; message-send-mail-function 'message-smtpmail-send-it)
136 ;; uncomment to debug smtp sending problems
137 ;; (setq smtpmail-debug-info t)
139 Then, add to `.emacs`:
141 (autoload 'notmuch "~/.emacs.d/my-notmuch" "notmuch mail" t)
144 ## Add a key binding to add/remove/toggle a tag
146 The `notmuch-{search,show}-{add,remove}-tag` functions are very useful
147 for making quick tag key bindings. For instance, here's an example
148 of how to make a key binding to add the "spam" tag and remove the
149 "inbox" tag in notmuch-show-mode:
151 In notmuch versions up to 0.11.x
153 (define-key notmuch-show-mode-map "S"
155 "mark message as spam"
157 (notmuch-show-add-tag "spam")
158 (notmuch-show-remove-tag "inbox")))
160 Starting from notmuch 0.12 the functions `notmuch-show-add-tag` and
161 `notmuch-show-remove-tag` have changed to be more versatile and lost
162 noninteractive use. When upgrading to 0.12 the above needs to be
165 (define-key notmuch-show-mode-map "S"
167 "mark message as spam"
169 (notmuch-show-tag-message "+spam" "-inbox")))
171 You can do the same for threads in `notmuch-search-mode` by just
172 replacing "show" with "search" in the called functions.
174 Starting from notmuch 0.12 use `notmuch-search-tag-thread` instead:
176 (define-key notmuch-search-mode-map "S"
178 "mark messages in thread as spam"
180 (notmuch-show-tag-thread "+spam" "-inbox")))
182 Starting from notmuch 0.13 use `notmuch-search-tag` -- it has a little
183 different usage syntax:
185 (define-key notmuch-search-mode-map "S"
187 "mark messages in thread as spam"
189 (notmuch-search-tag '("+spam" "-inbox"))))
191 The definition above makes use of a lambda function, but you could
192 also define a separate function first:
194 (defun notmuch-show-tag-spam ()
195 "mark message as spam"
197 (notmuch-show-add-tag "spam")
198 (notmuch-show-remove-tag "inbox")))
199 (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)
201 (See above for analogy how to apply this for notmuch 0.12 and later)
203 Here's a more complicated example of how to add a toggle "deleted"
206 (define-key notmuch-show-mode-map "d"
208 "toggle deleted tag for message"
210 (if (member "deleted" (notmuch-show-get-tags))
211 (notmuch-show-remove-tag "deleted")
212 (notmuch-show-add-tag "deleted"))))
214 And version for notmuch 0.12
216 (define-key notmuch-show-mode-map "d"
218 "toggle deleted tag for message"
220 (notmuch-show-tag-message
221 (if (member "deleted" (notmuch-show-get-tags))
222 "-deleted" "+deleted"))))
224 ## Adding many tagging keybindings
226 If you want to have have many tagging keybindings, you can save the typing
227 the few lines of boilerplate for every binding (for versions before 0.12,
228 you will need to change notmuch-show-apply-tag-macro).
230 (eval-after-load 'notmuch-show
231 '(define-key notmuch-show-mode-map "`" 'notmuch-show-apply-tag-macro))
233 (setq notmuch-show-tag-macro-alist
235 '("m" "+notmuch::patch" "+notmuch::moreinfo" "-notmuch::needs-review")
236 '("n" "+notmuch::patch" "+notmuch::needs-review" "-notmuch::pushed")
237 '("o" "+notmuch::patch" "+notmuch::obsolete"
238 "-notmuch::needs-review" "-notmuch::moreinfo")
239 '("p" "-notmuch::pushed" "-notmuch::needs-review"
240 "-notmuch::moreinfo" "+pending")
241 '("P" "-pending" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::pushed")
242 '("r" "-notmuch::patch" "+notmuch::review")
243 '("s" "+notmuch::patch" "-notmuch::obsolete" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::stale")
244 '("t" "+notmuch::patch" "-notmuch::needs-review" "+notmuch::trivial")
245 '("w" "+notmuch::patch" "+notmuch::wip" "-notmuch::needs-review")))
247 (defun notmuch-show-apply-tag-macro (key)
249 (let ((macro (assoc key notmuch-show-tag-macro-alist)))
250 (apply 'notmuch-show-tag-message (cdr macro))))
252 ## Restore reply-to-all key binding to 'r'
254 Starting from notmuch 0.12 the 'r' key is bound to reply-to-sender instead of
255 reply-to-all. Here's how to swap the reply to sender/all bindings in show mode:
257 (define-key notmuch-show-mode-map "r" 'notmuch-show-reply)
258 (define-key notmuch-show-mode-map "R" 'notmuch-show-reply-sender)
262 (define-key notmuch-search-mode-map "r" 'notmuch-search-reply-to-thread)
263 (define-key notmuch-search-mode-map "R" 'notmuch-search-reply-to-thread-sender)
266 ## How to do FCC/BCC...
268 The Emacs interface to notmuch will automatically add an `Fcc`
269 header to your outgoing mail so that any messages you send will also
270 be saved in your mail store. You can control where this copy of the
271 message is saved by setting the variables `message-directory` (which
272 defines a base directory) and `notmuch-fcc-dirs` which defines the
273 subdirectory relative to `message-directory` in which to save the
274 mail. Enter a directory (without the maildir `/cur` ending which
275 will be appended automatically). To customize both variables at the
276 same time, use the fancy command:
278 M-x customize-apropos<RET>\(notmuch-fcc-dirs\)\|\(message-directory\)
280 This mechanism also allows you to select different folders to be
281 used for the outgoing mail depending on your selected `From`
282 address. Please see the documentation for the variable
283 `notmuch-fcc-dirs` in the customization window for how to arrange
286 ## How to customize `notmuch-saved-searches`
288 When starting notmuch, a list of saved searches and message counts is
289 displayed, replacing the older `notmuch-folders` command. The set of
290 saved searches displayed can be modified directly from the notmuch
291 interface (using the `[save]` button next to a previous search) or by
292 customising the variable `notmuch-saved-searches`.
294 An example setting might be:
296 (setq notmuch-saved-searches '(("inbox" . "tag:inbox")
297 ("unread" . "tag:inbox AND tag:unread")
298 ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
300 Of course, you can have any number of saved searches, each configured
301 with any supported search terms (see "notmuch help search-terms").
303 Some users find it useful to add `and not tag:delete` to those
304 searches, as they use the `delete` tag to mark messages as
305 deleted. This causes messages that are marked as deleted to be removed
306 from the commonly used views of messages. Use whatever seems most
309 ## Viewing HTML messages with an external viewer
311 The emacs client can display an HTML message inline using either the
312 `html2text` library or some text browser, like w3m or lynx. This is
313 controlled by the `mm-text-html-renderer` variable.
315 The first option is theorically better, because it can generate
316 strings formatted for emacs and do whatever you want, e.g., substitute
317 text inside <b> tags for bold text in the buffer. The library, however
318 is still in a very early development phase and cannot yet process
319 properly many elements, like tables and <style> directives, and even
320 the generated text is often poorly formatted.
322 Among the available browsers, w3m seems to do a better job converting
323 the html, and if you have the w3m emacs package, you can use it,
324 instead of the w3m-standalone, and thus preserve the text formatting.
326 But if the rendering fails for one reason or another, or if you really
327 need to see the graphical presentation of the HTML message, it can be
328 useful to display the message in an external viewer, such as a web
329 browser. Here's a little script that Keith Packard wrote, which he
335 cat "$@" > "$dir"/msg
336 if munpack -C "$dir" -t < "$dir"/msg 2>&1 | grep 'Did not find'; then
337 sed -n '/[Hh][Tt][Mm][Ll]/,$p' "$dir"/msg > $dir/part1.html
340 for i in "$dir"/part*; do
341 if grep -q -i -e '<html>' -e 'text/html' "$i"; then
348 Save that script somewhere in your `${PATH}`, make it executable,
349 and change the invocation of `iceweasel` to any other HTML viewer if
350 necessary. Then within the emacs client, press '|' to pipe the
351 current message, then type "view-html".
353 Keith mentions the following caveat, "Note that if iceweasel isn't
354 already running, it seems to shut down when the script exits. I
357 ## msmtp, message mode and multiple accounts
359 As an alternative to running a mail server such as sendmail or postfix
360 just to send email, it is possible to use
361 [msmtp](http://msmtp.sourceforge.net/). This small application will
362 look like `/usr/bin/sendmail` to a MUA such as emacs message mode, but
363 will just forward the email to an external SMTP server. It's fairly
364 easy to set up and it supports several accounts for using different
365 SMTP servers. The msmtp pages have several examples.
367 A typical scenario is that you want to use the company SMTP server
368 for email coming from your company email address, and your personal
369 server for personal email. If msmtp is passed the envelope address
370 on the command line (the -f/--from option) it will automatically
371 pick the matching account. The only trick here seems to be getting
372 emacs to actually pass the envelope from. There are a number of
373 overlapping configuration variables that control this, and it's a
374 little confusion, but setting these three works for me:
376 - `mail-specify-envelope-from`: `t`
378 - `message-sendmail-envelope-from`: `header`
380 - `mail-envelope-from`: `header`
382 With that in place, you need a `.msmtprc` with the accounts configured
383 for the domains you want to send out using specific SMTP servers and
384 the rest will go to the default account.
386 If you have a hard time getting the above to work for you, as I did,
387 it's also possible to add a message-send-mail-hook in your .emacs to
388 send the from header explicitly as an argument to msmtp as described
389 [here](http://www.emacswiki.org/cgi-bin/wiki/GnusMSMTP#toc2) on the
393 ## <span id="address_completion">Address completion when composing</span>
395 There are currently three solutions to this:
399 [bbdb](http://bbdb.sourceforge.net) is a contact database for emacs
400 that works quite nicely together with message mode, including
401 address autocompletion.
403 ### notmuch database as an address book
405 You can also use the notmuch database as a mail address book itself.
406 To do this you need a command line tool that outputs likely address
407 candidates based on a search string. There are currently three
410 * The python tool `notmuch_address.py` (`git clone
411 http://commonmeasure.org/~jkr/git/notmuch_addresses.git`) (slower, but
412 no compilation required so good for testing the setup)
415 [addrlookup](http://github.com/spaetz/vala-notmuch) (faster, but
416 needs compiling). The addrlookup binary needs to be compiled.
418 `http://github.com/spaetz/vala-notmuch/raw/static-sources/src/addrlookup.c`
421 cc -o addrlookup addrlookup.c `pkg-config --cflags --libs gobject-2.0` -lnotmuch
423 * Shell/fgrep/perl combination [nottoomuch-addresses.sh](http://www.iki.fi/too/nottoomuch/nottoomuch-addresses/).
424 This tools maintains it's own address "database" gathered from email
425 files notmuch knows and search from that "database" is done by `fgrep(1)`.
427 You can perform tab-completion using any of these programs.
428 Just add the following to your .emacs:
430 (require 'notmuch-address)
431 (setq notmuch-address-command "/path/to/address_fetching_program")
432 (notmuch-address-message-insinuate)
436 [GooBook](http://code.google.com/p/goobook/) is a command-line tool for
437 accessing Google Contacts. Install and set it up according to its documentation.
439 To use GooBook with notmuch, use this wrapper script and set it up like the
443 goobook query "$*" | sed 's/\(.*\)\t\(.*\)\t.*/\2 \<\1\>/' | sed '/^$/d'
445 You can add the sender of a message to Google Contacts by piping the message
446 (`notmuch-show-pipe-message`) to `goobook add`.
448 ## How to sign/encrypt messages with gpg
450 Messages can by signed using gpg by invoking
451 `M-x mml-secure-sign-pgpmime` (or `M-x mml-secure-encrypt-pgpmime`).
452 These functions are available via the standard `message-mode` keybindings
453 `C-c C-m s p` and `C-c C-m c p`. To sign outgoing mail by default, use the
454 `message-setup-hook` in your `.emacs` file:
456 ;; Sign messages by default.
457 (add-hook 'message-setup-hook 'mml-secure-sign-pgpmime)
459 This inserts the required `<#part sign=pgpmime>` into the beginning
460 of the mail text body and will be converted into a pgp signature
461 when sending (so one can just manually delete that line if signing
464 Alternatively, you may prefer to use `mml-secure-message-sign-pgpmime` instead
465 of `mml-secure-sign-pgpmime` to sign the whole message instead of just one
468 ### Troubleshooting message-mode gpg support
470 - If you have trouble with expired subkeys, you may have encountered
471 emacs bug #7931. This is fixed in git commit 301ea744c on
472 2011-02-02. Note that if you have the Debian package easypg
473 installed, it will shadow the fixed version of easypg included with
476 ## Multiple identities using gnus-alias
478 [gnus-alias](http://www.emacswiki.org/emacs/GnusAlias) allows you to
479 define multiple identities when using `message-mode`. You can specify
480 the from address, organization, extra headers (including *Bcc*), extra
481 body text, and signature for each identity. Identities are chosen
482 based on a set of rules. When you are in message mode, you can switch
483 identities using gnus-alias.
487 - put `gnus-alias.el` on your load Emacs-Lisp load path (add new directory
488 to load path by writing `(add-to-list 'load-path "/some/load/path")` into
491 - Add the following to your `.emacs`
493 (autoload 'gnus-alias-determine-identity "gnus-alias" "" t)
494 (add-hook 'message-setup-hook 'gnus-alias-determine-identity)
496 Looking into `gnus-alias.el` gives a bit more information...
498 ### Example Configuration
500 Here is an example configuration.
502 ;; Define two identities, "home" and "work"
503 (setq gnus-alias-identity-alist
505 nil ;; Does not refer to any other identity
506 "John Doe <jdoe@example.net>" ;; Sender address
507 nil ;; No organization header
508 nil ;; No extra headers
509 nil ;; No extra body text
513 "John Doe <john.doe@example.com>"
515 (("Bcc" . "john.doe@example.com"))
517 "~/.signature.work")))
518 ;; Use "home" identity by default
519 (setq gnus-alias-default-identity "home")
520 ;; Define rules to match work identity
521 (setq gnus-alias-identity-rules
522 '(("work" ("any" "john.doe@\\(example\\.com\\|help\\.example.com\\)" both) "work"))
523 ;; Determine identity when message-mode loads
524 (add-hook 'message-setup-hook 'gnus-alias-determine-identity)
526 When `gnus-alias` has been loaded (using autoload, require, *M-x load-library*
527 or *M-x load-file* (load-file takes file path -- therefore it can be used
528 without any `.emacs` changes)) the following commands can be used to get(/set)
529 more information (some of these have "extensive documentation"):
531 M-x describe-variable RET gnus-alias-identity-alist
532 M-x describe-variable RET gnus-alias-identity-rules
533 M-x describe-variable RET gnus-alias-default-identity
535 M-x customize-group RET gnus-alias RET
537 M-x gnus-alias-customize RET
539 The last two do the same thing.
541 See also the **Usage:** section in `gnus-alias.el`.