1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 #Tips and Tricks for using notmuch with Emacs
6 The main Notmuch message reading client is **notmuch.el**, which is an
7 [emacs](http://www.gnu.org/software/emacs/) major mode, and is
8 included in the notmuch package.
12 To use the Notmuch emacs mode, first add the following line to your
17 or you can load the package via autoload:
19 (autoload 'notmuch "notmuch" "notmuch mail" t)
21 Then, either run "emacs -f notmuch", or execute the command `M-x
22 notmuch` from within a running emacs.
24 ## Navigating & reading mails
26 When first starting notmuch in emacs, you will be presented with the
27 notmuch "hello" page. From here you can do searches, see lists of
28 recent searches, saved searches, message tags, help information, etc.
30 Executing a search will open a new buffer in `notmuch-search-mode`
31 displaying the search results. Each line in the search results
32 represents a message thread. Hitting the '?' key will show help for
35 In general, the 'q' will kill the current notmuch buffer and return
36 you to the previous buffer (sort of like a 'pop').
38 In search mode, navigating to a thread and hitting return will then
39 open a new buffer in `notmuch-show-mode`, which will show the actual
40 message contents of the thread.
44 In any notmuch mode, you can start a new message by hitting the 'm'
45 key. To reply to a message or thread, just hit the 'r' key.
47 When composing new messages, you will be entered in emacs's
48 `message-mode`, which is a powerful mode for composing and sending
49 messages. When in message mode, you can type `C-c ?` for help.
51 If you would like to use address autocompletion when composing
52 messages, see [address completion](#address_completion).
54 When you are ready to send a message, type `C-c C-c`. By default
55 message mode will use your sendmail command to send mail, so make sure
56 that works. One annoying standard configuration of message mode is
57 that it will hide the sent mail in your emacs frame stack, but it will
58 not close it. If you type several mails in an emacs session they will
59 accumulate and make switching between buffers more annoying. You can
60 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
61 in your `.emacs` file (or doing `M-x
62 customize-variable<RET>message-kill-buffer-on-exit<RET>`) which will
63 really close the mail window after sending it.
67 Using the `M-x mml-attach-file` command, you can attach any file to be
68 sent with your mail. By default this command is bound to the menu item
69 *Attachments--Attach File* with the key binding `C-c C-a`. The
70 variable `mml-dnd-attach-options` (`M-x
71 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
72 allow the prompting for various attachment options (such as
73 inline/attachment) if you want to do that.
75 For those who prefer a more graphical interface, you can also simply
76 drag and drop files from a file manager into a mail composition window
77 to have them attached. In Ubuntu this works without any modifications
78 if files are dragged from the file manager.
80 And for those who prefer working from command line, the following
81 script opens new emacs window with empty message and attaches files
82 mentioned as script arguments. (Note: The script expects that you have
83 `(server-start)` in your `.emacs` file.)
88 fullpath=$(readlink --canonicalize $1)
89 attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
92 emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
97 # Advanced tips and tweaks
99 ## Use separate emacs lisp file for notmuch configuration
101 Instead of adding notmuch configuration code to `.emacs`, there
102 is an option to collect those to a separate file (which is only
103 loaded when `notmuch` is invoked). To do this, write, for example
104 a file called `~/.emacs.d/my-notmuch.el`:
106 ;; my-notmuch.el -- my notmuch mail configuration
109 ;; add here stuff required to be configured *before*
110 ;; notmuch is loaded;
112 ; uncomment and modify in case some elisp files are not found in load-path
113 ; (add-to-list 'load-path "~/vc/ext/notmuch/emacs")
118 ;; add here stuff required to be configured *after*
119 ;; notmuch is loaded;
121 ;(setq user-mail-address (notmuch-user-primary-email)
122 ; user-full-name (notmuch-user-name))
124 ; uncomment & modify if you want to use external smtp server to send mail
125 ; (setq smtpmail-smtp-server "smtp.server.tld"
126 ; message-send-mail-function 'message-smtpmail-send-it)
128 Then, add to `.emacs`:
130 (autoload 'notmuch "~/.emacs.d/my-notmuch" "notmuch mail" t)
133 ## Add a key binding to add/remove/toggle a tag
135 The `notmuch-{search,show}-{add,remove}-tag` functions are very useful
136 for making quick tag key bindings. For instance, here's an example
137 of how to make a key binding to add the "spam" tag and remove the
138 "inbox" tag in notmuch-show-mode:
140 (define-key notmuch-show-mode-map "S"
142 "mark message as spam"
144 (notmuch-show-add-tag "spam")
145 (notmuch-show-remove-tag "inbox")))
147 You can do the same for threads in `notmuch-search-mode` by just
148 replacing "show" with "search" in the called functions.
150 The definition above makes use of a lambda function, but you could
151 also define a separate function first:
153 (defun notmuch-show-tag-spam()
154 "mark message as spam"
156 (notmuch-show-add-tag "spam")
157 (notmuch-show-remove-tag "inbox")))
158 (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)
160 Here's a more complicated example of how to add a toggle "deleted"
163 (define-key notmuch-show-mode-map "d"
165 "toggle deleted tag for message"
167 (if (member "deleted" (notmuch-show-get-tags))
168 (notmuch-show-remove-tag "deleted")
169 (notmuch-show-add-tag "deleted"))))
171 ## How to do FCC/BCC...
173 The Emacs interface to notmuch will automatically add an `Fcc`
174 header to your outgoing mail so that any messages you send will also
175 be saved in your mail store. You can control where this copy of the
176 message is saved by setting the variables `message-directory` (which
177 defines a base directory) and `notmuch-fcc-dirs` which defines the
178 subdirectory relative to `message-directory` in which to save the
179 mail. Enter a directory (without the maildir `/cur` ending which
180 will be appended automatically). To customize both variables at the
181 same time, use the fancy command:
183 M-x customize-apropos<RET>\(notmuch-fcc-dirs\)\|\(message-directory\)
185 This mechanism also allows you to select different folders to be
186 used for the outgoing mail depending on your selected `From`
187 address. Please see the documentation for the variable
188 `notmuch-fcc-dirs` in the customization window for how to arrange
191 ## How to customize `notmuch-saved-searches`
193 When starting notmuch, a list of saved searches and message counts is
194 displayed, replacing the older `notmuch-folders` command. The set of
195 saved searches displayed can be modified directly from the notmuch
196 interface (using the `[save]` button next to a previous search) or by
197 customising the variable `notmuch-saved-searches`.
199 An example setting might be:
201 (setq notmuch-saved-searches '(("inbox" . "tag:inbox")
202 ("unread" . "tag:inbox AND tag:unread")
203 ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
205 Of course, you can have any number of saved searches, each configured
206 with any supported search terms (see "notmuch help search-terms").
208 Some users find it useful to add `and not tag:delete` to those
209 searches, as they use the `delete` tag to mark messages as
210 deleted. This causes messages that are marked as deleted to be removed
211 from the commonly used views of messages. Use whatever seems most
214 ## Viewing HTML messages with an external viewer
216 The emacs client can display an HTML message inline using either the
217 `html2text` library or some text browser, like w3m or lynx. This is
218 controlled by the `mm-text-html-renderer` variable.
220 The first option is theorically better, because it can generate
221 strings formatted for emacs and do whatever you want, e.g., substitute
222 text inside <b> tags for bold text in the buffer. The library, however
223 is still in a very early development phase and cannot yet process
224 properly many elements, like tables and <style> directives, and even
225 the generated text is often poorly formatted.
227 Among the available browsers, w3m seems to do a better job converting
228 the html, and if you have the w3m emacs package, you can use it,
229 instead of the w3m-standalone, and thus preserve the text formatting.
231 But if the rendering fails for one reason or another, or if you really
232 need to see the graphical presentation of the HTML message, it can be
233 useful to display the message in an external viewer, such as a web
234 browser. Here's a little script that Keith Packard wrote, which he
240 cat "$@" > "$dir"/msg
241 if munpack -C "$dir" -t < "$dir"/msg 2>&1 | grep 'Did not find'; then
242 sed -n '/[Hh][Tt][Mm][Ll]/,$p' "$dir"/msg > $dir/part1.html
245 for i in "$dir"/part*; do
246 if grep -q -i -e '<html>' -e 'text/html' "$i"; then
253 Save that script somewhere in your `${PATH}`, make it executable,
254 and change the invocation of `iceweasel` to any other HTML viewer if
255 necessary. Then within the emacs client, press '|' to pipe the
256 current message, then type "view-html".
258 Keith mentions the following caveat, "Note that if iceweasel isn't
259 already running, it seems to shut down when the script exits. I
262 ## msmtp, message mode and multiple accounts
264 As an alternative to running a mail server such as sendmail or postfix
265 just to send email, it is possible to use
266 [msmtp](http://msmtp.sourceforge.net/). This small application will
267 look like `/usr/bin/sendmail` to a MUA such as emacs message mode, but
268 will just forward the email to an external SMTP server. It's fairly
269 easy to set up and it supports several accounts for using different
270 SMTP servers. The msmtp pages have several examples.
272 A typical scenario is that you want to use the company SMTP server
273 for email coming from your company email address, and your personal
274 server for personal email. If msmtp is passed the envelope address
275 on the command line (the -f/--from option) it will automatically
276 pick the matching account. The only trick here seems to be getting
277 emacs to actually pass the envelope from. There are a number of
278 overlapping configuration variables that control this, and it's a
279 little confusion, but setting these three works for me:
281 - `mail-specify-envelope-from`: `t`
283 - `message-sendmail-envelope-from`: `header`
285 - `mail-envelope-from`: `header`
287 With that in place, you need a `.msmtprc` with the accounts configured
288 for the domains you want to send out using specific SMTP servers and
289 the rest will go to the default account.
291 If you have a hard time getting the above to work for you, as I did,
292 it's also possible to add a message-send-mail-hook in your .emacs to
293 send the from header explicitly as an argument to msmtp as described
294 [here](http://www.emacswiki.org/cgi-bin/wiki/GnusMSMTP#toc2) on the
298 ## <span id="address_completion">Address completion when composing</span>
300 There are currently two solutions to this:
302 [bbdb](http://bbdb.sourceforge.net) is a contact database for emacs
303 that works quite nicely together with message mode, including
304 address autocompletion.
306 You can also use the notmuch database as a mail address book itself.
307 To do this you need a command line tool that outputs likely address
308 candidates based on a search string. There are currently two
311 * The python tool `notmuch_address.py` (`git clone
312 http://commonmeasure.org/~jkr/git/notmuch_addresses.git`) (slower, but
313 no compilation required so good for testing the setup)
316 [addrlookup](http://github.com/spaetz/vala-notmuch) (faster, but
317 needs compiling). The addrlookup binary needs to be compiled.
319 `http://github.com/spaetz/vala-notmuch/raw/static-sources/src/addrlookup.c`
322 cc -o addrlookup addrlookup.c `pkg-config --cflags --libs gobject-2.0` -lnotmuch
324 You can perform tab-completion using either of these programs. Just add the following to your .emacs:
326 (require 'notmuch-address)
327 (setq notmuch-address-command "/path/to/address_fetching_program")
328 (notmuch-address-message-insinuate)
331 ## How to sign/encrypt messages with gpg
333 Messages can by signed using gpg by invoking `M-x
334 mml-secure-sign-pgpmime` (or `M-x
335 mml-secure-encrypt-pgpmime`). These functions are available via the
336 standard `message-mode` keybindings `C-c C-m s p` and `C-c C-m c
337 p`. To sign outgoing mail by default, use the `message-setup-hook`
338 in your `.emacs` file:
340 ;; Sign messages by default.
341 (add-hook 'message-setup-hook 'mml-secure-sign-pgpmime)
343 This inserts the required `<#part sign=pgpmime>` into the beginning
344 of the mail text body and will be converted into a pgp signature
345 when sending (so one can just manually delete that line if signing
348 Alternatively, you may prefer to use `mml-secure-message-sign-pgpmime` instead
349 of `mml-secure-sign-pgpmime` to sign the whole message instead of just one
352 ### Troubleshooting message-mode gpg support
354 - If you have trouble with expired subkeys, you may have encounted
355 emacs bug #7931. This is fixed in git commit 301ea744c on
356 2011-02-02. Note that if you have the Debian package easypg
357 installed, it will shadow the fixed version of easypg included with