doomemacs/modules/email/mu4e/README.org

#+TITLE:   email/mu4e
#+DATE:    April 8, 2017
#+SINCE:   v2.0
#+STARTUP: inlineimages

* Table of Contents :TOC:
- [[#description][Description]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
  - [[#nixos][NixOS]]
- [[#features][Features]]
- [[#configuration][Configuration]]
  - [[#offlineimap][offlineimap]]
  - [[#mbsync][mbsync]]
  - [[#mu-and-mu4e][mu and mu4e]]
  - [[#orgmsg][OrgMsg]]
  - [[#mu4e-alert][mu4e-alert]]
- [[#troubleshooting][Troubleshooting]]
  - [[#no-such-file-or-directory-mu4e][=No such file or directory, mu4e=]]
  - [[#void-function-org-time-add-error-on-gentoo][~(void-function org-time-add)~ error on Gentoo]]

* Description
This module makes Emacs an email client, using ~mu4e~.

#+begin_quote
I want to live in Emacs, but as we all know, living is incomplete without email.
So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing
combined with org-mode for writing emails? /Yes please./

It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email
via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
#+end_quote

** Module Flags
+ =+gmail= Enables gmail-specific configuration for mail ~To~ or ~From~ a gmail
  address, or a maildir with ~gmail~ in the name.
+ =+org= Use =org-msg= for composing email in Org, then sending a multipart text
  (ASCII export) and HTML message.

** Plugins
+ [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]]
+ =+org=
  + [[https://github.com/jeremy-compostella/org-msg][org-msg]]

* Prerequisites
This module requires:

+ Either ~mbsync~ (recommended, default) or ~offlineimap~ (to sync mail with)
+ ~mu~, to index your downloaded messages and to provide the ~mu4e~ package.

#+name: Install Matrix
| Platform      | Install command        | Base packages       |
|---------------+------------------------+---------------------|
| MacOS         | ~brew install <pkgs>~    | =mu=                  |
| Arch          | ~pacman -S <pkgs>~       | (AUR, ~yay -S~) =mu=    |
| openSUSE      | ~zypper install <pkgs>~  | =maildir-utils=, =mu4e= |
| Fedora        | ~dnf install <pkgs>~     | =maildir-utils=       |
| Debian/Ubuntu | ~apt-get install <pkgs>~ | =maildir-utils=, =mu4e= |

The install either the =isync= (=mbsync=) or =offlineimap= package.

To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default.
You can also run a local SMTP server like =sendmail= or =postfix=, or use an SMTP
forwarder such as =msmtp= (recommended).

If you use =msmtp=, you'll likely want to add the following to your
=config.el=:
#+begin_src emacs-lisp
(setq sendmail-program "/usr/bin/msmtp"
        send-mail-function #'smtpmail-send-it
        message-sendmail-f-is-evil t
        message-sendmail-extra-arguments '("--read-envelope-from")
        message-send-mail-function #'message-send-mail-with-sendmail)
#+end_src

** NixOS
#+BEGIN_SRC nix
environment.systemPackages = with pkgs; [
    mu
    # And one of the following
    isync
    offlineimap
];
#+END_SRC

[[https://github.com/Emiller88/dotfiles/blob/5eaabedf1b141c80a8d32e1b496055231476f65e/modules/shell/mail.nix][An example of setting up mbsync and mu with home-manager]]

* Features
+ Tidied mu4e headers view, with flags from =all-the-icons=
+ Consistent coloring of reply depths (across compose and gnus modes)
+ Prettified =mu4e:main= view
+ Cooperative locking of the =mu= process. Another Emacs instance may request
  access, or grab the lock when it's available.
+ =org-msg= integration with =+org=, which can be toggled per-message, with revamped style and
  an accent color
+ Gmail integrations with the =+gmail= flag
+ Email notifications with =mu4e-alert=, and (on Linux) a customised notification style

* Configuration
** offlineimap
This module uses =mbsync= by default. To use =offlineimap=, change ~+mu4e-backend~:

#+BEGIN_SRC emacs-lisp
(setq +mu4e-backend 'offlineimap)
#+END_SRC

Next, you need to write a configuration file for =offlineimap=. Mine can be found
[[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I
use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find a *very*
detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]].

Next you can download your email with ~offlineimap -o~. This may take a while,
especially if you have thousands of mails.

You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.

** mbsync
The steps needed to set up =mu4e= with =mbsync= are very similar to the ones for
[[#offlineimap][offlineimap]].

Start with writing a ~~/.mbsyncrc~. An example for Gmail can be found on
[[http://pragmaticemacs.com/emacs/migrating-from-offlineimap-to-mbsync-for-mu4e/][pragmaticemacs.com]]. A non-Gmail example is available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. The [[http://isync.sourceforge.net/mbsync.html][manual
page]] contains all needed information to set up your own.

Next you can download your email with ~mbsync --all~. This may take a while, but
should be quicker than =offlineimap= ;).

You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.

*** Faster syncing
It's possible to use IMAP IDLE to be quickly notified of updates, then use a
tailored =mbsync= command to just fetch the new changes.

If this is of interest, this approach can be seen [[https://tecosaur.github.io/emacs-config/config.html#fetching][in @tecosaur's config]] where
[[https://gitlab.com/shackra/goimapnotify][goimapnotify]] is used for this.

** mu and mu4e
You should have your email downloaded already. If you have not, you need to set
=offlineimap= or =mbsync= up before you proceed.

Before you can use =mu4e= or the CLI program =mu=, you need to index your email
initially. How to do that differs a little depending on the version of =mu= you
use. You can check your version with ~mu --version~.

For =mu= *>=1.4* you need to run two commands:
#+BEGIN_SRC sh
mu init --maildir ~/.mail --my-address email@example.com
mu index
#+END_SRC

=mu= *<1.4* only requires one command:
#+BEGIN_SRC sh
mu index --maildir ~/.mail
#+END_SRC

Then configure Emacs to use your email address:

#+BEGIN_SRC emacs-lisp :tangle no
;; Each path is relative to `+mu4e-mu4e-mail-path', which is ~/.mail by default
(set-email-account! "Lissner.net"
  '((mu4e-sent-folder       . "/Lissner.net/Sent Mail")
    (mu4e-drafts-folder     . "/Lissner.net/Drafts")
    (mu4e-trash-folder      . "/Lissner.net/Trash")
    (mu4e-refile-folder     . "/Lissner.net/All Mail")
    (smtpmail-smtp-user     . "henrik@lissner.net")
    (user-mail-address      . "henrik@lissner.net")    ;; only needed for mu < 1.4
    (mu4e-compose-signature . "---\nHenrik Lissner"))
  t)
#+END_SRC

*** Gmail
With the =+gmail= flag, integrations are applied which account for the different
behaviour of Gmail.

The integrations are applied when using addresses which contain =@gmail.com= or
have =gmail= in the maildir name. You can use ~+mu4e-gmail-addresses~ when you want
an address to be treated as such but it meets neither conditions (e.g. with
Gsuite).

** OrgMsg
With the =+org= flag, =org-msg= is installed, and ~org-msg-mode~ is enabled before
composing the first message. To disable ~org-msg-mode~ by default, simply
#+BEGIN_SRC emacs-lisp :tangle no
(setq mu4e-compose--org-msg-toggle-next nil)
#+END_SRC

To toggle org-msg for a single message, just apply the universal argument to the
compose or reply command (=SPC u= with ~evil~, =C-u= otherwise).

The accent color that Doom uses can be customised by setting
~+org-msg-accent-color~ to a CSS color string.

** mu4e-alert
This provides notifications through the [[https://github.com/jwiegley/alert][alert]] library.

If you don't like this, simply add
#+begin_src emacs-lisp
(package! mu4e-alert :disable t)
#+end_src
to your [[elisp:(find-file (expand-file-name "packages.el" doom-private-dir))][packages.el]] and it will not be used.

* Troubleshooting
** =No such file or directory, mu4e=
You will get =No such file or directory, mu4e= errors if you don't run ~doom
sync~ after installing =mu= through your package manager.

Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*).
if that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~
you can do that by...
#+BEGIN_SRC emacs-lisp :tangle no
(add-to-list 'load-path "your/path/to/mu4e")
;; if you installed it using your package manager
(add-to-list 'load-path "/usr/share/emacs/site-lisp/mu4e")
;; if you built from source
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
#+END_SRC

If you have completely lost your install then you can use this handy command!

#+BEGIN_SRC  shell
find / -type d -iname '*mu4e*'
# I reccomend rerouting all of the error to /dev/null
find / -type d -iname '*mu4e*' 2> /dev/null
#+END_SRC

** ~(void-function org-time-add)~ error on Gentoo
Gentoo users will see this error because [[https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/mu/files/70mu-gentoo.el#n2][the =net-mail/mu= package eagerly loads
=mu4e= (which pulls in =org=) much too early]]; before Emacs reads =~/.emacs.d=.
So early, that it loads the built-in version of org-mode, rather than the newer
version that Doom installs.

Later versions of the =net-mail/mu= package have [[https://gitweb.gentoo.org/repo/gentoo.git/commit/net-mail/mu?id=770e1fccb119fbce8ba6d16021a3598123f212ff][fixed this issue]], but you may
need to switch to the unstable build of =net-mail/mu= to see it.