:email mu4e

…

1. Description

This module makes Emacs an email client, using mu4e.

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).

1.2. 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.

1.4. TODO Hacks

No hacks documented for this module.

2. Prerequisites

This module requires:

  • mu, to index your downloaded messages and to provide the mu4e package.
  • A program to sync your mail. This module comes with builtin support for mbsync (recommended, default) or offlineimap but you can sync mail in other ways too.
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

Then install either the isync (mbsync) or offlineimap package.

To send mail, mu4e uses 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:

# ⎘
;; add to $DOOMDIR/config.el
(after! mu4e
  (setq sendmail-program (executable-find "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))

2.1. NixOS

# ⎘
environment.systemPackages = with pkgs; [
    mu
    # And one of the following
    isync
    offlineimap
];

An example of setting up mbsync and mu with home-manager

3. Usage

  • 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

4. Configuration

4.1. offlineimap

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

# ⎘
(setq +mu4e-backend 'offlineimap)

Next, you need to write a configuration file for offlineimap. Mine can be found in my dotfiles repository. It is configured to download mail to \~/.mail. I use unix pass to securely store my login credentials. You can find a very detailed configuration 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 section.

4.2. mbsync

The steps needed to set up mu4e with mbsync are very similar to the ones for offlineimap.

Start with writing a ~/.mbsyncrc. An example for Gmail can be found on pragmaticemacs.com. A non-Gmail example is available as a gist here. The 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 section.

4.2.1. 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 in @tecosaur’s config where goimapnotify is used for this.

4.3. Fetching your mail in other ways

You also have the possiblity to invoke an arbitary shell command to fetch your mail by disabling this module’s backend selection and setting the value of the mu4e-get-mail-command to the command you want to execute.

# ⎘
(setq +mu4e-backend nil)
(after! mu4e
  (setq mu4e-get-mail-command "your_command"))

If your command prompts you for a passphrase, you might want to change the value of the mu4e~get-mail-password-regexp such that mu4e will recognize the prompt and let you provide the passphrase from within Emacs.

4.4. 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:

# ⎘
$ mu init --maildir ~/.mail --my-address email@example.com
$ mu index

mu <1.4 only requires one command:

# ⎘
$ mu index --maildir ~/.mail

Be sure to replace ~/.mail with the directory containing your mail.

Then configure Emacs to use your email address:

# ⎘
;; Each path is relative to the path of the maildir you passed to mu
(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)

If you use multiple email accounts, defining them with set-email-account! will automatically set the appropriate account context when replying to emails in that account’s maildir. mu4e-context-policy and mu4e-compose-context-policy can be modified to change context behavior when opening mu4e and composing email:

# ⎘
(setq mu4e-context-policy 'ask-if-none
      mu4e-compose-context-policy 'always-ask)

If you send mail from various email aliases for different services, +mu4e-personal-addresses can be set per-context with set-email-account!. If you are not replying to an email to or from one of the specified aliases, you will be prompted for an alias to send from.

4.4.1. Gmail

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

The integrations are applied to addresses with both “@gmail.com” in the account address and “gmail” in the account maildir, as well as accounts listed in +mu4e-gmail-accounts. Any domain can be specified, so G Suite accounts can benefit from the integrations:

# ⎘
;; if "gmail" is missing from the address or maildir, the account must be
;; specified manually in `+mu4e-gmail-accounts':
(setq +mu4e-gmail-accounts '(("hlissner@gmail.com" . "/hlissner")
			     ("example@example.com" . "/example")))

If you only use Gmail, you can improve performance due to the way Gmail presents messages over IMAP:

# ⎘
;; don't need to run cleanup after indexing for gmail
(setq mu4e-index-cleanup nil
      ;; because gmail uses labels as folders we can use lazy check since
      ;; messages don't really "move"
      mu4e-index-lazy-check t)

Also, note that Gmail’s IMAP settings must have “When I mark a message in IMAP as deleted: Auto-Expunge off - Wait for the client to update the server.” and “When a message is marked as deleted and expunged from the last visible IMAP folder: Move the message to the trash” for the integrations to work as expected.

4.5. 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:

# ⎘
(setq mu4e-compose--org-msg-toggle-next nil)

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.

4.6. mu4e-alert

This provides notifications through the alert library.

If you don’t like this, use the following to disable them:

# ⎘
;; add to $DOOMDIR/packages.el
(package! mu4e-alert :disable t)

5. Troubleshooting

5.1. 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 install it and add it to your load-path you can do that by:

# ⎘
(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")

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

# ⎘
find / -type d -iname '*mu4e*'
# I recommend rerouting all of the errors to /dev/null
find / -type d -iname '*mu4e*' 2> /dev/null

5.2. (void-function org-time-add) error on Gentoo

Gentoo users will see this error because 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 fixed this issue, but you may need to switch to the unstable build of net-mail/mu to see it.

6. TODO Appendix

This module has no appendix yet. Write one?