spacemacs/layers/+email/notmuch/README.org

#+TITLE: Notmuch layer

#+TAGS: e-mail|layer

[[file:img/notmuch.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#sending-and-receiving-emails][Sending and Receiving emails]]
    - [[#receiving-emails][Receiving emails]]
    - [[#sending-emails-with-thunderbird][Sending emails with Thunderbird]]
    - [[#sending-emails-with-msmtp][Sending emails with msmtp]]
  - [[#tags-to-apply-when-deleting][Tags to apply when deleting]]
  - [[#see-also][See also]]
- [[#key-bindings][Key bindings]]
  - [[#global-bindings][Global bindings]]
  - [[#show-mode][Show mode]]
  - [[#evilified-key-bindings][Evilified key bindings]]
    - [[#hello-mode][Hello mode]]
    - [[#search-mode][Search mode]]
    - [[#show-mode-1][Show mode]]
    - [[#tree-mode][Tree mode]]
- [[#spacemacs-layout-integration][Spacemacs layout integration]]

* Description
Notmuch offers a fast, global-search and tag-based email system to
use within your text editor or in a terminal.

This layer integrates the Notmuch Emacs package into Spacemacs.

** Features:
- Email searching
- Email tagging

* Install
In order to use this layer you must install Notmuch separately.

To install not much follow the instructions in [[https://notmuchmail.org/notmuch-emacs/#index2h2][installation instructions]].

Then add this layer to your =~/.spacemacs=. You will need to add =notmuch= to
the existing =dotspacemacs-configuration-layers= list in this file.

* Configuration
** Sending and Receiving emails
For this you will need an external program.

*** Receiving emails
To be able to receive email you will need to configure an external program to do
it. See the [[https://notmuchmail.org/howto/][receive mail]] section.

After you configured your email fetcher program, maybe you would like to
synchronize the email each time you call =notmuch=, in order to do that you
could customize the variable =notmuch-hello-mode-hook= to call a lisp function
that calls your email syncing utility.

*** Sending emails with Thunderbird
You could use thunderbird
[[http://pragmaticemacs.com/emacs/use-emacs-for-thunderbird-emails/]]

*** Sending emails with msmtp
Download and Install [[http://msmtp.sourceforge.net/download.html][msmtp]]

Configure =~/.mailrc= with the path where =msmtp= is found.

For example:

#+SRCNAME: contents of ~/.mailrc

#+BEGIN_SRC rc
  set sendmail="/usr/local/bin/msmtp"
#+END_SRC

Configure =~/.msmtprc= [[http://msmtp.sourceforge.net/doc/msmtprc.txt][example]]

** Tags to apply when deleting
You can specifiy which tags you want to apply when you delete an email by
setting the layer variable =notmuch-message-deleted-tags=.

Default value is to add the =deleted= tag and remove both =inbox= and
=unread= tags.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((notmuch :variables notmuch-message-deleted-tags '("+deleted" "-inbox" "-unread"))))
#+END_SRC

** See also
Refer to the official notmuch website for more information:
[[https://notmuchmail.org/]]

* Key bindings
** Global bindings

| Key binding   | Command                                      |
|---------------+----------------------------------------------|
| ~SPC a e n N~ | Start notmuch                                |
| ~SPC a e n n~ | Start helm/counsil notmuch                   |
| ~SPC a e n j~ | Start a notmuch jump search                  |
| ~SPC a e n s~ | Start a notmuch search                       |
| ~SPC l o n~   | Start notmuch in a custom layout, "@Notmuch" |

** Show mode

| Key binding     | Command                                                                        |
|-----------------+--------------------------------------------------------------------------------|
| ~SPC m a~       | [ATTACHMENTS] Save all attachments                                             |
|-----------------+--------------------------------------------------------------------------------|
| ~SPC m P o~     | [PATCH] Open github patch in a new buffer                                      |
|-----------------+--------------------------------------------------------------------------------|
| ~SPC m p m~     | [PART] Choose the mime type to use for displaying                              |
| ~SPC m p \vert~ | [PART] Pipe part at point to an external command                               |
| ~SPC m p o~     | [PART] View part at point (prompt for a viewer)                                |
| ~SPC m p v~     | [PART] View part at point in an external viewer                                |
| ~SPC m p s~     | [PART] Save part at point to a file                                            |
|-----------------+--------------------------------------------------------------------------------|
| ~SPC m s c~     | [STASH] Copy =CC= to kill-ring                                                 |
| ~SPC m s d~     | [STASH] Copy =timestamp= to kill-ring                                          |
| ~SPC m s G~     | [STASH] Copy =From/To/Cc/Message-Id= of current message to kill-ring           |
| ~SPC m s l~     | [STASH] [Mailing List Archive] Copy =ML Archive URI= to kill-ring              |
| ~SPC m s L~     | [STASH] [Mailing List Archive] Copy =ML Archive URI= to kill-ring and visit it |
| ~SPC m s i~     | [STASH] Copy =message-id= to kill-ring                                         |
| ~SPC m s I~     | [STASH] Copy =message-id= without =id:= prefix to kill-ring                    |
| ~SPC m s f~     | [STASH] Copy =From address= to kill-ring                                       |
| ~SPC m s F~     | [STASH] Copy =filename= to kill-ring                                           |
| ~SPC m s s~     | [STASH] Copy =Subject= to kill-ring                                            |
| ~SPC m s t~     | [STASH] Copy =To address= to kill-ring                                         |
| ~SPC m s T~     | [STASH] Copy =tags= to kill-ring                                               |

** Evilified key bindings
*** Hello mode

| Key binding | Command                              |
|-------------+--------------------------------------|
| ~TAB~       | Jump to next widget                  |
| ~S-TAB~     | Jump to previous widget              |
| ~J~         | Jump to a saved search               |
| ~s~         | Show threads matching QUERY          |
| ~=~ or ~g~  | Refresh buffer                       |
| ~M-=~       | Refresh all open notmuch buffers     |
| ~?~         | Open notmuch help buffer             |
| ~G~         | Pull new messages and refresh buffer |
| ~m~         | Open new mail buffer                 |
| ~q~         | Kill notmuch buffer                  |
| ~v~         | Show current notmuch version         |
| ~z~         | Open notmuch tree buffer             |

*** Search mode

| Key binding | Command                  |
|-------------+--------------------------|
| ~J~         | Jump to saved search     |
| ~*~         | [Thread] Add/Remove tags |
| ~+~         | [Message] Add tags       |
| ~-~         | [Message] Remove tags    |
| ~a~         | [Message] Archive        |

*** Show mode

| Key binding | Description                |
|-------------+----------------------------|
| ~o~         | Open all messages          |
| ~O~         | Close all messages         |
| ~n~         | Show next open message     |
| ~N~         | Show next message          |
| ~p~         | Show previous open message |
| ~P~         | Show previous message      |
| ~C-n~       | Show next thread           |
| ~C-p~       | Show previous thread       |
| ~d~         | Delete messages down       |
| ~D~         | Delete messages up         |
| ~J~         | Jump search                |
| ~L~         | Filter current search      |
| ~gf~        | Find file or URL at point  |
| ~gg~        | Jump to top                |
| ~G~         | Jump to bottom             |
| ~gr~        | Refresh buffer             |
| ~gR~        | Refresh all buffers        |
| ~m~         | Compose mail               |

*** Tree mode

| Key binding | Command                  |
|-------------+--------------------------|
| ~*~         | [Thread] Add/Remove tags |
| ~+~         | [Message] Add tags       |
| ~-~         | [Message] Remove tags    |
| ~a~         | [Message] Archive        |

* Spacemacs layout integration
This layer defines a [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#layouts-and-workspaces][Spacemacs custom layout]] and automatically adds notmuch
buffers to this layout. The name and the key binding for the layout can be
customized with the following layer variables:
- =notmuch-spacemacs-layout-name= for the layout name,
- =notmuch-spacemacs-layout-binding= for the key binding.

The following example configures the layout with the default name and binding:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (notmuch :variables notmuch-spacemacs-layout-name "@Notmuch"
                        notmuch-spacemacs-layout-binding "n")))
#+END_SRC