[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
#Tips and Tricks for using notmuch with Emacs
-* How to do FCC/BCC...
+[[!toc levels=2]]
- Any notmuch reply will automatically include your primary email
- address in a BCC so that any messages you send will (eventually) end
- up in your mail store as well.
+The main Notmuch message reading client is **notmuch.el**, which is an
+[emacs](http://www.gnu.org/software/emacs/) major mode, and is
+included in the notmuch package.
- But this doesn't do anything for messages that you compose that are
- not replies. So we need to get sane message-mode FCC figured
- out. Some investigation is still needed here.
+## Setup
-* How to customize notmuch-folders
+To use the Notmuch emacs mode, first add the following line to your
+`.emacs` rc file:
- There's a "notmuch-folder" command available in the emacs client
- that displays a list of "folders" and the number of messages in
- each. Each folder is simply a named search specification. To
- configure this mode, edit your ${HOME}/.emacs file and include text
- something like the following:
+ (require 'notmuch)
- (setq notmuch-folders '(("inbox" . "tag:inbox")
- ("unread" . "tag:inbox AND tag:unread")
- ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
+Then, either run "emacs -f notmuch", or execute the command `M-x
+notmuch` from within a running emacs.
- Of course, you can have any number of folders, each configured
- with any supported search terms (see "notmuch help search-terms").
+## Navigating & reading mails
-* Viewing HTML messages with an external viewer
+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.
- The emacs client can often display an HTML message inline, but it
- sometimes fails for one reason or another, (or is perhaps inadequate
- if you really need to see the graphical presentation of the HTML
- message).
+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 this case, 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:
+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](#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 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
+send 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`) 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
+
+## 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:
+
+ (define-key notmuch-show-mode-map "S"
+ (lambda ()
+ "mark message as spam"
+ (interactive)
+ (notmuch-show-add-tag "spam")
+ (notmuch-show-remove-tag "inbox")))
+
+You can do the same for threads in `notmuch-search-mode` by just
+replacing "show" with "search" in the called functions.
+
+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)
+
+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"))))
+
+## 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 <style> 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=3D`mktemp -d`
+ 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
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".
+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](http://msmtp.sourceforge.net/). 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 support several account 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:
+
+ - `mail-specify-envelope-from`: `t`
+
+ - `message-sendmail-envelope-from`: `header`
+
+ - `mail-envelope-from`: `header`
+
+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.
+
+## <span id="address_completion">Address completion when composing</span>
+
+There are currently two solutions to this:
+
+[bbdb](http://bbdb.sourceforge.net) is a contact database for emacs
+that works quite nicely together with message mode, including
+address autocompletion.
+
+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 two
+available:
+
+ * The python tool `notmuch_address.py` (`git clone
+ http://jkr.acm.jhu.edu/git/notmuch_addresses.git`) (slower, but
+ no compilation required so good for testing the setup)
+
+ * The vala-based
+ [addrlookup](http://github.com/spaetz/vala-notmuch) (faster, but
+ needs compiling). The addrlookup binary needs to be compiled.
+ Grab
+ `http://github.com/spaetz/vala-notmuch/raw/static-sources/src/addrlookup.c`
+ and build it with:
+
+ cc -o addrlookup addrlookup.c `pkg-config --cflags --libs gobject-2.0` -lnotmuch
+
+EUDC is integrated into emacs and is needed for tab completion of
+email addresses. See [this
+mail](http://mid.gmane.org/87fx3uflkx.fsf@jhu.edu)
+(id:87fx3uflkx.fsf@jhu.edu) for more information.
+
+## 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).
- 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."
+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.
projects / notmuch-wiki / blobdiff