git.notmuchmail.org Git - notmuch-wiki/blob - notmuch-emacs.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Notmuch Emacs Interface
   3
   4 One of the more popular Notmuch message reading clients is **notmuch.el**, or
   5 `notmuch-mode`, an [Emacs](https://www.gnu.org/software/emacs/) major mode for
   6 interacting with Notmuch. It is included in the Notmuch package (as
   7 `elpa-notmuch` within the `notmuch` package in current Debian or as
   8 `notmuch-emacs` in Debian 10 or prior). The [[screenshots|screenshots]] give a
   9 good overview of the mode.
  10
  11 This page is a basic guide for setting up and using Notmuch with Emacs. See also
  12 the [[tips and tricks page|emacstips]] for more advanced details.
  13
  14 [[!toc levels=2]]
  15
  16 ## Prerequisites
  17
  18 The Notmuch Emacs interface uses the Notmuch [command line
  19 interface](https://notmuchmail.org/doc/latest/man1/notmuch.html) to
  20 interact with the Notmuch database and your mail store. Please make
  21 sure you've [[set up Notmuch|getting-started]] first.
  22
  23 ## Installation
  24
  25 Due to the dependency on the command line interface, the Notmuch Emacs interface
  26 version must be compatible with the Notmuch version. On Linux, the easiest way
  27 to ensure this is to use the package(s) in your distribution's package
  28 repository.
  29
  30 If you've installed Notmuch from a [git
  31 checkout](https://git.notmuchmail.org/git/notmuch) or a [source
  32 release](https://notmuchmail.org/releases/), Notmuch Emacs is included by
  33 default.
  34
  35 It is **not** recommended to install Notmuch Emacs from the Emacs Lisp Package
  36 Archive (ELPA), as the version there is likely not in sync with the command line
  37 interface.
  38
  39 ## Setup
  40
  41 First, you need to tell Emacs about Notmuch. Add this to your `.emacs` rc file:
  42
  43         (autoload 'notmuch "notmuch" "notmuch mail" t)
  44
  45 or if you always want to load Notmuch when you start Emacs:
  46
  47         (require 'notmuch)
  48
  49 To start Notmuch Emacs, either run `emacs -f notmuch`, or execute the command
  50 `M-x notmuch RET` from within a running Emacs. This will bring you to the
  51 Notmuch Hello view.
  52
  53 ## Customization
  54
  55 Notmuch Emacs uses the Emacs customization interface extensively for
  56 configuration. Execute `M-x customize-group RET notmuch RET` to get to the
  57 Notmuch main customization group.
  58
  59 ### <span id="notmuch_init_file"> Notmuch Emacs configuration file </span>
  60
  61 After Notmuch is loaded `notmuch-init-file` (typically
  62  `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists
  63 it is loaded. Most Emacs lisp based configuration not suitable via
  64 customization can be put there instead of `~/.emacs`.
  65
  66 ## Navigating & reading mails
  67
  68 When first starting Notmuch in Emacs, you will be presented with the
  69 Notmuch "hello" page.  If it exits with an error after writing
  70 "Welcome to notmuch. You have" you need to do the basic Notmuch setup
  71 first (see above).
  72 From here you can do searches, see lists of recent
  73 searches, saved searches, message tags, help information, etc.
  74
  75 Executing a search will open a new buffer in `notmuch-search-mode`
  76 displaying the search results.  Each line in the search results
  77 represents a message thread.  Hitting the '?' key will show help for
  78 this mode.
  79
  80 In general, the 'q' will kill the current Notmuch buffer and return
  81 you to the previous buffer (sort of like a 'pop').
  82
  83 In search mode, navigating to a thread and hitting return will then
  84 open a new buffer in `notmuch-show-mode`, which will show the actual
  85 message contents of the thread.
  86
  87 ## Sending mail
  88
  89 In any Notmuch mode, you can start a new message by hitting the 'm'
  90 key.  To reply to a message or thread, just hit the 'r' key.
  91
  92 When composing new messages, you will be entered in Emacs's
  93 `message-mode`, which is a powerful mode for composing and sending
  94 messages.  When in message mode, you can type `C-c ?` for help.
  95
  96 If you would like to use address autocompletion when composing
  97 messages, see [address completion](/emacstips#index13h2).
  98
  99 When you are ready to send a message, type `C-c C-c`. By default
 100 message mode will use your sendmail command to send mail, so make sure
 101 that works. One annoying standard configuration of message mode is
 102 that it will hide the sent mail in your Emacs frame stack, but it will
 103 not close it. If you type several mails in an Emacs session they will
 104 accumulate and make switching between buffers more annoying. You can
 105 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
 106 in your `.emacs` file
 107 (or doing `M-x customize-variable<RET>message-kill-buffer-on-exit<RET>`)
 108 which will really close the mail window after sending it.
 109
 110 ## Attaching files
 111
 112 Using the `M-x mml-attach-file` command, you can attach any file to be
 113 sent with your mail. By default this command is bound to the menu item
 114 *Attachments--Attach File* with the key binding `C-c C-a`. The
 115 variable `mml-dnd-attach-options` (`M-x
 116 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
 117 allow the prompting for various attachment options (such as
 118 inline/attachment) if you want to do that.
 119
 120 For those who prefer a more graphical interface, you can also simply
 121 drag and drop files from a file manager into a mail composition window
 122 to have them attached. In Ubuntu this works without any modifications
 123 if files are dragged from the file manager.
 124
 125 And for those who prefer working from command line, the following
 126 script opens new Emacs window with empty message and attaches files
 127 mentioned as script arguments. (Note: The script expects that you have
 128 `(server-start)` in your `.emacs` file.)
 129
 130         #!/bin/sh
 131         attach_cmds=""
 132         while [ $# -gt 0 ]; do
 133             fullpath=$(readlink --canonicalize "$1")
 134             attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
 135             shift
 136         done
 137         emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
 138
 139 Also, if you're the kind of person who forgets to add attachments,
 140 there's a cure for that disease. See [Never forget
 141 attachments](/emacstips#index27h2) for all the details.