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

#+TITLE: Mu4e layer

#+TAGS: e-mail|layer

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#commands][Commands]]
  - [[#global-bindings][Global bindings]]
  - [[#headers-mode][Headers mode]]
  - [[#view-mode][View mode]]
  - [[#compose-mode][Compose mode]]
- [[#configuration][Configuration]]
  - [[#maildirs-extension][Maildirs extension]]
  - [[#multiple-accounts][Multiple Accounts]]
  - [[#async-mode][Async mode]]
  - [[#attachment-directory][Attachment directory]]
  - [[#example-configuration][Example configuration]]
  - [[#notifications][Notifications]]
    - [[#os-notifications][OS notifications]]
    - [[#mode-line-notifications][Mode-line notifications]]
  - [[#spacemacs-layout-integration][Spacemacs layout integration]]
  - [[#org-mu4e-integration][Org-mu4e integration]]
    - [[#mu4e-link-support-in-org-mode][Mu4e link support in Org mode]]
    - [[#composing-org-mode-messages-in-mu4e][Composing Org mode messages in mu4e]]
- [[#see-also][See also]]

* Description
This layer adds support for the =Mu4e= email client.

** Features:
- Search, read, reply, move, and delete email.
- Search-based: no folders, only queries.
- UI optimized for speed: quick keystrokes for common actions.
- Very extendable and customizable.
- Integration with Helm.
- Maildir summary using [[https://github.com/agpchil/mu4e-maildirs-extension][mu4e-mailidirs-extension]]
- Notifications using [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]]

* Install
In order to use this layer you must install =mu= and =mu4e= separately.
Typically =mu4e= will be bundled with =mu= (this is the case on many Linux
distributions).

If you're on macOS and install =mu= using Homebrew, you must specify the
location of your Emacs binary at install time using the EMACS environment
variable, as well as passing the =--with-emacs= option:

#+BEGIN_SRC shell
  brew install mu --with-emacs
#+END_SRC

If the installation directory of =mu4e= is not in Emacs' load path, you can set
the layer variable =mu4e-installation-path=, for example:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables
                        mu4e-installation-path "/usr/share/emacs/site-lisp")))
#+END_SRC

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

* Commands
** Global bindings

| Key binding            | Command                         |
|------------------------+---------------------------------|
| ~SPC a e m~            | Start mu4e                      |
| ~SPC m S~ or ~SPC m /~ | Search emails (requires helm)   |
| ~SPC m C~              | Search contacts (requires helm) |
| ~C-x m~                | Compose new message             |

** Headers mode

| Key binding | Command                                                     |
|-------------+-------------------------------------------------------------|
| ~J~         | Go to next unread thread marking other mail read on the way |
| ~C-j~       | Next header                                                 |
| ~C-k~       | Previous header                                             |

** View mode

| Key binding | Command                                                     |
|-------------+-------------------------------------------------------------|
| ~J~         | Go to next unread thread marking other mail read on the way |
| ~C-j~       | Next header                                                 |
| ~C-k~       | Previous header                                             |

** Compose mode

| Key binding            | Command                        |
|------------------------+--------------------------------|
| ~SPC m c~ or ~SPC m ,~ | Send the message and exit      |
| ~SPC m k~ or ~SPC m a~ | Kill the message buffer        |
| ~SPC m s~              | Auto-save and bury the message |
| ~SPC m f~              | Add file as attachment         |
| ~SPC m o~              | Compose in Org-mode syntax     |

* Configuration
Configuration varies too much to give precise instructions. What follows is one
example configuration. Refer to =mu4e='s manual for more detailed configuration
instructions.

** Maildirs extension
The [[https://github.com/agpchil/mu4e-maildirs-extension][maildirs extension]] adds a list of all your maildirs to the main =mu4e= view
that by default shows the unread and total mail counts for all your mail under
your base mail directory.

The maildirs extension is not enabled by default. To activate it, change the
variable =mu4e-use-maildirs-extension= to a non-nil value:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables
                        mu4e-use-maildirs-extension t)))
#+END_SRC

** Multiple Accounts
With =mu 0.9.16=, =mu4e= comes with a native contexts feature for managing
multiple accounts.

The following example is taken from the manual:

#+BEGIN_SRC emacs-lisp
  (setq mu4e-contexts
    `( ,(make-mu4e-context
    :name "Private"
    :enter-func (lambda () (mu4e-message "Switch to the Private context"))
    ;; leave-func not defined
    :match-func (lambda (msg)
      (when msg
        (mu4e-message-contact-field-matches msg
          :to "aliced@home.example.com")))
    :vars '(  ( user-mail-address      . "aliced@home.example.com"  )
       ( user-full-name     . "Alice Derleth" )
       ( mu4e-compose-signature .
         (concat
           "Alice Derleth\n"
           "Lauttasaari, Finland\n"))))
       ,(make-mu4e-context
    :name "Work"
    :enter-func (lambda () (mu4e-message "Switch to the Work context"))
    ;; leave-fun not defined
    :match-func (lambda (msg)
      (when msg
        (mu4e-message-contact-field-matches msg
          :to "aderleth@miskatonic.example.com")))
    :vars '(  ( user-mail-address      . "aderleth@miskatonic.example.com" )
       ( user-full-name     . "Alice Derleth" )
       ( mu4e-compose-signature .
         (concat
           "Prof. Alice Derleth\n"
           "Miskatonic University, Dept. of Occult Sciences\n"))))))

  ;; set `mu4e-context-policy` and `mu4e-compose-policy` to tweak when mu4e should
  ;; guess or ask the correct context, e.g.

  ;; start with the first (default) context;
  ;; default is to ask-if-none (ask when there's no context yet, and none match)
  ;; (setq mu4e-context-policy 'pick-first)

  ;; compose with the current context is no context matches;
  ;; default is to ask
  ;; (setq mu4e-compose-context-policy nil)
#+END_SRC

Note: We used to have a hack to support multiple accounts with older version of
=mu= but we removed it to encourage people to update their version and use the
new contexts feature.

** Async mode
=mu4e= can send mails in async mode, which speeds up sending as you do not have
to wait for the email to be sent. This is off by default but you can enable
it by setting the ~mu4e-enable-async-operations~ variable when including the
layer.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables
                        mu4e-enable-async-operations t)))
#+END_SRC

** Attachment directory
By default =mu4e= will save attachment files to =$HOME=, but this layer changes
that to =$HOME/Downloads= if it exists. You can override this in your
=dotspacemacs/user-config=:

#+BEGIN_SRC emacs-lisp
  (setq mu4e-attachment-dir "~/files")
#+END_SRC

** Example configuration
#+BEGIN_SRC emacs-lisp
  ;;; Set up some common mu4e variables
  (setq mu4e-maildir "~/.mail"
        mu4e-trash-folder "/Trash"
        mu4e-refile-folder "/Archive"
        mu4e-get-mail-command "mbsync -a"
        mu4e-update-interval nil
        mu4e-compose-signature-auto-include nil
        mu4e-view-show-images t
        mu4e-view-show-addresses t)

  ;;; Mail directory shortcuts
  (setq mu4e-maildir-shortcuts
        '(("/gmail/INBOX" . ?g)
          ("/college/INBOX" . ?c)))

  ;;; Bookmarks
  (setq mu4e-bookmarks
        `(("flag:unread AND NOT flag:trashed" "Unread messages" ?u)
          ("date:today..now" "Today's messages" ?t)
          ("date:7d..now" "Last 7 days" ?w)
          ("mime:image/*" "Messages with images" ?p)
          (,(mapconcat 'identity
                       (mapcar
                        (lambda (maildir)
                          (concat "maildir:" (car maildir)))
                        mu4e-maildir-shortcuts) " OR ")
           "All inboxes" ?i)))
#+END_SRC

** Notifications
=mu4e-alert= is an extension that provides desktop notifications and adds the
count of unread messages to the modeline.

[[https://raw.githubusercontent.com/iqbalansari/mu4e-alert/master/screenshots/mu4e-alert-in-action.png]]

For an extended documentation of the available customizations please refer to
[[https://github.com/iqbalansari/mu4e-alert#user-content-customizations][mu4e-alert's documentation]]

*** OS notifications
To enable notifications about new messages, add the following line to your
=dotspacemacs/user-config=:

#+BEGIN_SRC emacs-lisp
  (setq mu4e-enable-notifications t)
#+END_SRC

or use layer variables when you add the layer to
=dotspacemacs-configuration-layers=:

#+BEGIN_SRC emacs-lisp
  (mu4e :variables mu4e-enable-notifications t)
#+END_SRC

By default, notifications will be shown in the =*Messages*= buffer. To enable
desktop notifications about new messages, add the following lines to
your =dotspacemacs/user-config=, according to your operating system and the
installed libraries:

#+BEGIN_SRC emacs-lisp
  (with-eval-after-load 'mu4e-alert
    ;; Enable Desktop notifications
    (mu4e-alert-set-default-style 'notifications)) ; For Linux.
    ;; (mu4e-alert-set-default-style 'libnotify))  ; Alternative for Linux
    ;; (mu4e-alert-set-default-style 'notifier))   ; For macOS (through the
                                                   ; terminal notifier app).
    ;; (mu4e-alert-set-default-style 'growl))      ; Alternative for macOS.
#+END_SRC

*** Mode-line notifications
To enable mode-line display about new messages, add the following line to
your =dotspacemacs/user-config=:

#+BEGIN_SRC emacs-lisp
  (setq mu4e-enable-mode-line t)
#+END_SRC

or use layer variables when you add the layer to
=dotspacemacs-configuration-layers=:

#+BEGIN_SRC emacs-lisp
  (mu4e :variables mu4e-enable-mode-line t)
#+END_SRC

** Spacemacs layout integration
A [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#layouts-and-workspaces][Spacemacs custom layout]] is defined by the layer. The name and the key binding
for it can be customized with the following layer variables:
- =mu4e-spacemacs-layout-name= for the layout name,
- =mu4e-spacemacs-layout-binding= for the key binding.
- =mu4e-spacemacs-kill-layout-on-exit= for automatically removing layout when
  quitting =mu4e=.

By default the values are:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables mu4e-spacemacs-layout-name "@Mu4e"
                        mu4e-spacemacs-layout-binding "m"
                        mu4e-spacemacs-kill-layout-on-exit t)))
#+END_SRC

** Org-mu4e integration
*** Mu4e link support in Org mode
Feature ~mu4e-org~ supports links to mu4e messages in Org mode in the form of
~[[mu4e:msgid::***][link text]]~. Enabled by default. You can disable it by
setting the ~mu4e-org-link-support~ variable when including the layer.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables
                        mu4e-org-link-support nil)))
#+END_SRC

*** Composing Org mode messages in mu4e
Feature ~org-mu4e~ supports composing emails in Org mode format. Disabled by
default. You can enable it by setting the ~mu4e-org-compose-support~ variable
when including the layer.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((mu4e :variables
                        mu4e-org-compose-support t)))
#+END_SRC

Then when composing, hit keys ~SPC m o~ to enable the
~org-mu4e-compose-org-mode~ mode. Note that you need to set the variable
~org-mu4e-convert-to-html~ if you want the message to be converted before
sending.

* See also
Refer to the official =mu= and =mu4e= documentation for additional info.
- [[http://www.djcbsoftware.nl/code/mu/mu4e/index.html][mu4e Manual]]