1 <!-- -*- mode: text; indent-tabs-mode: nil -*- -->
3 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
4 #Tips and Tricks for using notmuch with Emacs
8 The main Notmuch message reading client is **notmuch.el**, which is an
9 [emacs](http://www.gnu.org/software/emacs/) major mode, and is
10 included in the notmuch package.
14 To use the Notmuch emacs mode, first add the following line to your
19 or you can load the package via autoload:
21 (autoload 'notmuch "notmuch" "notmuch mail" t)
23 Then, either run "emacs -f notmuch", or execute the command `M-x
24 notmuch` from within a running emacs.
26 ## Navigating & reading mails
28 When first starting notmuch in emacs, you will be presented with the
29 notmuch "hello" page. From here you can do searches, see lists of
30 recent searches, saved searches, message tags, help information, etc.
32 Executing a search will open a new buffer in `notmuch-search-mode`
33 displaying the search results. Each line in the search results
34 represents a message thread. Hitting the '?' key will show help for
37 In general, the 'q' will kill the current notmuch buffer and return
38 you to the previous buffer (sort of like a 'pop').
40 In search mode, navigating to a thread and hitting return will then
41 open a new buffer in `notmuch-show-mode`, which will show the actual
42 message contents of the thread.
46 In any notmuch mode, you can start a new message by hitting the 'm'
47 key. To reply to a message or thread, just hit the 'r' key.
49 When composing new messages, you will be entered in emacs's
50 `message-mode`, which is a powerful mode for composing and sending
51 messages. When in message mode, you can type `C-c ?` for help.
53 If you would like to use address autocompletion when composing
54 messages, see [address completion](#address_completion).
56 When you are ready to send a message, type `C-c C-c`. By default
57 message mode will use your sendmail command to send mail, so make sure
58 that works. One annoying standard configuration of message mode is
59 that it will hide the sent mail in your emacs frame stack, but it will
60 not close it. If you type several mails in an emacs session they will
61 accumulate and make switching between buffers more annoying. You can
62 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
63 in your `.emacs` file (or doing `M-x
64 customize-variable<RET>message-kill-buffer-on-exit<RET>`) which will
65 really close the mail window after sending it.
69 Using the `M-x mml-attach-file` command, you can attach any file to be
70 sent with your mail. By default this command is bound to the menu item
71 *Attachments--Attach File* with the key binding `C-c C-a`. The
72 variable `mml-dnd-attach-options` (`M-x
73 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
74 allow the prompting for various attachment options (such as
75 inline/attachment) if you want to do that.
77 For those who prefer a more graphical interface, you can also simply
78 drag and drop files from a file manager into a mail composition window
79 to have them attached. In Ubuntu this works without any modifications
80 if files are dragged from the file manager.
82 And for those who prefer working from command line, the following
83 script opens new emacs window with empty message and attaches files
84 mentioned as script arguments. (Note: The script expects that you have
85 `(server-start)` in your `.emacs` file.)
90 fullpath=$(readlink --canonicalize "$1")
91 attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
94 emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
99 # Advanced tips and tweaks
101 ## Use separate emacs lisp file for notmuch configuration
103 Instead of adding notmuch configuration code to `.emacs`, there
104 is an option to collect those to a separate file (which is only
105 loaded when `notmuch` is invoked). To do this, write, for example
106 a file called `~/.emacs.d/my-notmuch.el`:
108 ;; my-notmuch.el -- my notmuch mail configuration
111 ;; add here stuff required to be configured *before*
112 ;; notmuch is loaded;
114 ; uncomment and modify in case some elisp files are not found in load-path
115 ; (add-to-list 'load-path "~/vc/ext/notmuch/emacs")
120 ;; add here stuff required to be configured *after*
121 ;; notmuch is loaded;
123 ;(setq user-mail-address (notmuch-user-primary-email)
124 ; user-full-name (notmuch-user-name))
126 ; uncomment & modify if you want to use external smtp server to send mail
127 ; (setq smtpmail-smtp-server "smtp.server.tld"
128 ; message-send-mail-function 'message-smtpmail-send-it)
132 (autoload 'notmuch "~/.emacs.d/my-notmuch" "notmuch mail" t)
135 ## Add a key binding to add/remove/toggle a tag
137 The `notmuch-{search,show}-{add,remove}-tag` functions are very useful
138 for making quick tag key bindings. For instance, here's an example
139 of how to make a key binding to add the "spam" tag and remove the
140 "inbox" tag in notmuch-show-mode:
142 In notmuch versions up to 0.11.x
144 (define-key notmuch-show-mode-map "S"
146 "mark message as spam"
148 (notmuch-show-add-tag "spam")
149 (notmuch-show-remove-tag "inbox")))
151 Starting from notmuch 0.12 (not released yet) the functions
152 `notmuch-show-add-tag` and `notmuch-show-remove-tag` have changed to
153 be more versatile and lost noninteractive use. When upgrading to 0.12
154 the above needs to be changed to this:
156 (define-key notmuch-show-mode-map "S"
158 "mark message as spam"
160 (notmuch-show-tag-message "+spam" "-inbox")))
162 You can do the same for threads in `notmuch-search-mode` by just
163 replacing "show" with "search" in the called functions.
165 (Starting from notmuch 0.12 use `notmuch-search-tag-thread` instead)
167 The definition above makes use of a lambda function, but you could
168 also define a separate function first:
170 (defun notmuch-show-tag-spam()
171 "mark message as spam"
173 (notmuch-show-add-tag "spam")
174 (notmuch-show-remove-tag "inbox")))
175 (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)
177 (See above for analogy how to apply this for notmuch 0.12 and later)
179 Here's a more complicated example of how to add a toggle "deleted"
182 (define-key notmuch-show-mode-map "d"
184 "toggle deleted tag for message"
186 (if (member "deleted" (notmuch-show-get-tags))
187 (notmuch-show-remove-tag "deleted")
188 (notmuch-show-add-tag "deleted"))))
190 And version for notmuch 0.12 (not released yet)
192 (define-key notmuch-show-mode-map "d"
194 "toggle deleted tag for message"
196 (notmuch-show-tag-message
197 (if (member "deleted" (notmuch-show-get-tags))
198 "-deleted" "+deleted"))))
200 ## Adding many tagging keybindings
202 If you want to have have many tagging keybindings, you can save the typing
203 the few lines of boilerplate for every binding (for versions before 0.12,
204 you will need to change notmuch-show-apply-tag-macro).
206 (eval-after-load 'notmuch-show
207 '(define-key notmuch-show-mode-map "`" 'notmuch-show-apply-tag-macro))
209 (setq notmuch-show-tag-macro-alist
211 '("m" "+notmuch::patch" "+notmuch::moreinfo" "-notmuch::needs-review")
212 '("n" "+notmuch::patch" "+notmuch::needs-review" "-notmuch::pushed")
213 '("o" "+notmuch::patch" "+notmuch::obsolete"
214 "-notmuch::needs-review" "-notmuch::moreinfo")
215 '("p" "-notmuch::pushed" "-notmuch::needs-review"
216 "-notmuch::moreinfo" "+pending")
217 '("P" "-pending" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::pushed")
218 '("r" "-notmuch::patch" "+notmuch::review")
219 '("s" "+notmuch::patch" "-notmuch::obsolete" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::stale")
220 '("t" "+notmuch::patch" "-notmuch::needs-review" "+notmuch::trivial")
221 '("w" "+notmuch::patch" "+notmuch::wip" "-notmuch::needs-review")))
223 (defun notmuch-show-apply-tag-macro (key)
225 (let ((macro (assoc key notmuch-show-tag-macro-alist)))
226 (apply 'notmuch-show-tag-message (cdr macro))))
228 ## Restore reply-to-all key binding to 'r'
230 Starting from notmuch 0.12 the 'r' key is bound to reply-to-sender instead of
231 reply-to-all. Here's how to swap the reply to sender/all bindings in show mode:
233 (define-key notmuch-show-mode-map "r" 'notmuch-show-reply)
234 (define-key notmuch-show-mode-map "R" 'notmuch-show-reply-sender)
238 (define-key notmuch-search-mode-map "r" 'notmuch-search-reply-to-thread)
239 (define-key notmuch-search-mode-map "R" 'notmuch-search-reply-to-thread-sender)
242 ## How to do FCC/BCC...
244 The Emacs interface to notmuch will automatically add an `Fcc`
245 header to your outgoing mail so that any messages you send will also
246 be saved in your mail store. You can control where this copy of the
247 message is saved by setting the variables `message-directory` (which
248 defines a base directory) and `notmuch-fcc-dirs` which defines the
249 subdirectory relative to `message-directory` in which to save the
250 mail. Enter a directory (without the maildir `/cur` ending which
251 will be appended automatically). To customize both variables at the
252 same time, use the fancy command:
254 M-x customize-apropos<RET>\(notmuch-fcc-dirs\)\|\(message-directory\)
256 This mechanism also allows you to select different folders to be
257 used for the outgoing mail depending on your selected `From`
258 address. Please see the documentation for the variable
259 `notmuch-fcc-dirs` in the customization window for how to arrange
262 ## How to customize `notmuch-saved-searches`
264 When starting notmuch, a list of saved searches and message counts is
265 displayed, replacing the older `notmuch-folders` command. The set of
266 saved searches displayed can be modified directly from the notmuch
267 interface (using the `[save]` button next to a previous search) or by
268 customising the variable `notmuch-saved-searches`.
270 An example setting might be:
272 (setq notmuch-saved-searches '(("inbox" . "tag:inbox")
273 ("unread" . "tag:inbox AND tag:unread")
274 ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
276 Of course, you can have any number of saved searches, each configured
277 with any supported search terms (see "notmuch help search-terms").
279 Some users find it useful to add `and not tag:delete` to those
280 searches, as they use the `delete` tag to mark messages as
281 deleted. This causes messages that are marked as deleted to be removed
282 from the commonly used views of messages. Use whatever seems most
285 ## Viewing HTML messages with an external viewer
287 The emacs client can display an HTML message inline using either the
288 `html2text` library or some text browser, like w3m or lynx. This is
289 controlled by the `mm-text-html-renderer` variable.
291 The first option is theorically better, because it can generate
292 strings formatted for emacs and do whatever you want, e.g., substitute
293 text inside <b> tags for bold text in the buffer. The library, however
294 is still in a very early development phase and cannot yet process
295 properly many elements, like tables and <style> directives, and even
296 the generated text is often poorly formatted.
298 Among the available browsers, w3m seems to do a better job converting
299 the html, and if you have the w3m emacs package, you can use it,
300 instead of the w3m-standalone, and thus preserve the text formatting.
302 But if the rendering fails for one reason or another, or if you really
303 need to see the graphical presentation of the HTML message, it can be
304 useful to display the message in an external viewer, such as a web
305 browser. Here's a little script that Keith Packard wrote, which he
311 cat "$@" > "$dir"/msg
312 if munpack -C "$dir" -t < "$dir"/msg 2>&1 | grep 'Did not find'; then
313 sed -n '/[Hh][Tt][Mm][Ll]/,$p' "$dir"/msg > $dir/part1.html
316 for i in "$dir"/part*; do
317 if grep -q -i -e '<html>' -e 'text/html' "$i"; then
324 Save that script somewhere in your `${PATH}`, make it executable,
325 and change the invocation of `iceweasel` to any other HTML viewer if
326 necessary. Then within the emacs client, press '|' to pipe the
327 current message, then type "view-html".
329 Keith mentions the following caveat, "Note that if iceweasel isn't
330 already running, it seems to shut down when the script exits. I
333 ## msmtp, message mode and multiple accounts
335 As an alternative to running a mail server such as sendmail or postfix
336 just to send email, it is possible to use
337 [msmtp](http://msmtp.sourceforge.net/). This small application will
338 look like `/usr/bin/sendmail` to a MUA such as emacs message mode, but
339 will just forward the email to an external SMTP server. It's fairly
340 easy to set up and it supports several accounts for using different
341 SMTP servers. The msmtp pages have several examples.
343 A typical scenario is that you want to use the company SMTP server
344 for email coming from your company email address, and your personal
345 server for personal email. If msmtp is passed the envelope address
346 on the command line (the -f/--from option) it will automatically
347 pick the matching account. The only trick here seems to be getting
348 emacs to actually pass the envelope from. There are a number of
349 overlapping configuration variables that control this, and it's a
350 little confusion, but setting these three works for me:
352 - `mail-specify-envelope-from`: `t`
354 - `message-sendmail-envelope-from`: `header`
356 - `mail-envelope-from`: `header`
358 With that in place, you need a `.msmtprc` with the accounts configured
359 for the domains you want to send out using specific SMTP servers and
360 the rest will go to the default account.
362 If you have a hard time getting the above to work for you, as I did,
363 it's also possible to add a message-send-mail-hook in your .emacs to
364 send the from header explicitly as an argument to msmtp as described
365 [here](http://www.emacswiki.org/cgi-bin/wiki/GnusMSMTP#toc2) on the
369 ## <span id="address_completion">Address completion when composing</span>
371 There are currently three solutions to this:
375 [bbdb](http://bbdb.sourceforge.net) is a contact database for emacs
376 that works quite nicely together with message mode, including
377 address autocompletion.
379 ### notmuch database as an address book
381 You can also use the notmuch database as a mail address book itself.
382 To do this you need a command line tool that outputs likely address
383 candidates based on a search string. There are currently three
386 * The python tool `notmuch_address.py` (`git clone
387 http://commonmeasure.org/~jkr/git/notmuch_addresses.git`) (slower, but
388 no compilation required so good for testing the setup)
391 [addrlookup](http://github.com/spaetz/vala-notmuch) (faster, but
392 needs compiling). The addrlookup binary needs to be compiled.
394 `http://github.com/spaetz/vala-notmuch/raw/static-sources/src/addrlookup.c`
397 cc -o addrlookup addrlookup.c `pkg-config --cflags --libs gobject-2.0` -lnotmuch
399 * Shell/fgrep/perl combination [nottoomuch-addresses.sh](http://www.iki.fi/too/nottoomuch/nottoomuch-addresses/).
400 This tools maintains it's own address "database" gathered from email
401 files notmuch knows and search from that "database" is done by fgrep(1).
403 You can perform tab-completion using any of these programs. Just add the following to your .emacs:
405 (require 'notmuch-address)
406 (setq notmuch-address-command "/path/to/address_fetching_program")
407 (notmuch-address-message-insinuate)
411 [GooBook](http://code.google.com/p/goobook/) is a command-line tool for
412 accessing Google Contacts. Install and set it up according to its documentation.
414 To use GooBook with notmuch, use this wrapper script and set it up like the
418 goobook query "$*" | sed 's/\(.*\)\t\(.*\)\t.*/\2 \<\1\>/' | sed '/^$/d'
420 You can add the sender of a message to Google Contacts by piping the message
421 (`notmuch-show-pipe-message`) to `goobook add`.
423 ## How to sign/encrypt messages with gpg
425 Messages can by signed using gpg by invoking `M-x
426 mml-secure-sign-pgpmime` (or `M-x
427 mml-secure-encrypt-pgpmime`). These functions are available via the
428 standard `message-mode` keybindings `C-c C-m s p` and `C-c C-m c
429 p`. To sign outgoing mail by default, use the `message-setup-hook`
430 in your `.emacs` file:
432 ;; Sign messages by default.
433 (add-hook 'message-setup-hook 'mml-secure-sign-pgpmime)
435 This inserts the required `<#part sign=pgpmime>` into the beginning
436 of the mail text body and will be converted into a pgp signature
437 when sending (so one can just manually delete that line if signing
440 Alternatively, you may prefer to use `mml-secure-message-sign-pgpmime` instead
441 of `mml-secure-sign-pgpmime` to sign the whole message instead of just one
444 ### Troubleshooting message-mode gpg support
446 - If you have trouble with expired subkeys, you may have encountered
447 emacs bug #7931. This is fixed in git commit 301ea744c on
448 2011-02-02. Note that if you have the Debian package easypg
449 installed, it will shadow the fixed version of easypg included with