[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
#Tips and Tricks for using notmuch with Emacs
-* How to do FCC/BCC...
+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.
-* How to customize notmuch-folders
+## Setup
-* ...
\ No newline at end of file
+To use the Notmuch emacs mode, first add the following line to your
+.emacs rc file:
+
+ (require 'notmuch)
+
+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 move, you can type "C-c ?" for help.
+
+If you would like to use address autocompletion, see the [address
+completion howto](#address_completion)" below.
+
+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/attachement) if you want to do that.
+
+For those who prefer graphics, you can also simply drag and drop files
+from a file manager into a mail composition window to have it attached
+(assuming you are using emacs with X support). At least in Ubuntu it
+works by dragging from the file manager without any modifications.
+
+-----
+
+<h2 id="advanced_tips">Advanced tips and tweaks</h2>
+
+* <span id="custom_keybinding">**Add a keybinding to add/remove/toggle a tag.**</span>
+
+ Here's an example of how to add a key binding to notmuch-show-mode
+ to toggle a "deleted" tag:
+
+ (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"))))
+
+ You can do the same for threads in notmuch-search-mode by just
+ replacing "show" with "search" in the called functions. This
+ definition makes use of a lambda function, but you could just as
+ easily defined a separate function first:
+
+ (defun notmuch-show-toggle-deleted-tag()
+ "toggle deleted tag for message"
+ (interactive)
+ (if (member "deleted" (notmuch-show-get-tags))
+ (notmuch-show-remove-tag "deleted")
+ (notmuch-show-add-tag "deleted")))
+ (define-key notmuch-show-mode-map "d" 'notmuch-show-toggle-deleted-tag)
+
+* <span id="fcc">**How to do FCC/BCC...**</span>
+
+ 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. But this doesn't do anything for
+ messages that you compose that are not replies.
+
+ Another method is to save the file in a folder of your local
+ Maildir, usually called FCC (file carbon copy). You can achieve this
+ 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 method will even allow you to select different outboxes
+ depending on your selected from address, if you need that
+ functionality. Please see the documentation on the variable in the
+ customization window for how to do so.
+
+* <span id="customize_notmuch_folder">**How to customize notmuch-folders**</span>
+
+ 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:
+
+ (setq notmuch-folders '(("inbox" . "tag:inbox")
+ ("unread" . "tag:inbox AND tag:unread")
+ ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
+
+ Of course, you can have any number of folders, each configured
+ with any supported search terms (see "notmuch help search-terms").
+
+ Personally, I find it fairly useful to add "not tag:delete" to those
+ views as I use that tag to mark messages as deleted and it
+ automatically removes them from my standard views. Use whatever
+ seems most useful to you.
+
+* **Viewing HTML messages with an external viewer**
+
+ 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).
+
+ 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:
+
+ #!/bin/sh
+ dir=3D`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](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">**how to get email address completion**</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). This is how you compile the (3rd party) tool
+ "addrlookup" to give you address completion:
+
+ - you need the addrlookup binary, first of all. 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`. That should give you
+ the binary that you can test already.
+
+ - EUDC is integrated into emacs and can be used for tab completion
+ of email addresses. The code I use is here
+ http://gist.github.com/359425. It was announce in [this
+ mail](http://mid.gmane.org/87fx3uflkx.fsf@jhu.edu)
+ (id:87fx3uflkx.fsf@jhu.edu) which contains links to the git
+ repositories which contain the files.
+
+* <span id="sign_messages_gpg">**how to sign/encrypt my messages with
+ gpg**</span>
+
+ You can manually sign your messages with gpg by invoking `M-x
+ mml-secure-sign-pgpmime` (or `M-x
+ mml-secure-encrypt-pgpmime`). These functions are available via the
+ convenient (*cough cough*) keybindings `C-c C-m s p` and `C-c C-m c
+ p` by default. To sign my outgoing mail by default, I use this hook
+ in my .emacs file:
+
+ ;;sign messages by default
+ (add-hook 'message-setup-hook 'mml-secure-sign-pgpmime)
+
+ This inserts the blurb `<#part sign=pgpmime>` into the beginning of
+ my mail text body and will be converted into a pgp signature when
+ sending (so I can just manually delete that line if I do not want a
+ mail to be signed).
projects / notmuch-wiki / blobdiff