doomemacs/modules/email/mu4e

:email mu4e

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • NixOS
• Usage
• Configuration
  • offlineimap
  • mbsync
    • Faster syncing
  • Fetching your mail in other ways
  • mu and mu4e
    • Gmail
  • Sending mail (SMTP)
    • SMTP server configuration
    • Authentication
      • Gmail
    • Connection type
    • Sending mail asynchronously
  • OrgMsg
  • mu4e-alert
  • Enabling automatic email fetching
• Troubleshooting
  • No such file or directory, mu4e
  • (void-function org-time-add) error on Gentoo
• Frequently asked questions
• Appendix

Description   unfold

This module makes Emacs an email client, using mu4e.

• Tidied mu4e headers view, with flags from doom-package:nerd-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.
• doom-package:org-msg integration with doom-module:+org, which can be toggled per-message, with revamped style and an accent color.
• Gmail integrations with the doom-module:+gmail flag.
• Email notifications with doom-package:mu4e-alert, and (on Linux) a customised notification style.

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

Maintainers

• @tecosaur

Become a maintainer?

Module flags

+gmail

Enable gmail-specific configuration for mail To or From a gmail address, or a maildir with gmail in the name.

+mbsync

Use mbsync to synchronize with mu.

+offlineimap

Use offlineimap to synchronize with mu.

+org

Use doom-package:org-msg for composing email in Org, then sending a multipart text (ASCII export) and HTML message.

Packages

• doom-package:mu4e-compat
• doom-package:org-msg if doom-module:+org

TODO Hacks

󱌣 This module's hacks haven't been documented yet. Document them?

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

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:

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

NixOS

environment.systemPackages = with pkgs; [
    mu
    # For nixpkgs versions after 23.05: this installs Emacs with mu4e already
    # included (you still need mu above; it just doesn't ship with mu4e anymore)
    ((emacsPackagesFor emacs).emacsWithPackages (epkgs: [ epkgs.mu4e ]))
    # And one of the following
    isync
    offlineimap
];

If you use home-manager you should specify mu4e as an additionally included package as follows (requires nixpkgs > 23.05):

programs.emacs = {
  enable = true;
  extraPackages = epkgs: [ epkgs.mu4e ];
}

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

TODO Usage

󱌣 This module has no usage documentation yet. Write some?

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

offlineimap

Enable this module with the +offlineimap flag, then write a configuration file for offlineimap (a sample config file can be found in offlineimap's repo).

Next, download your email with $ offlineimap -o. This may take a while, depending on how many emails need downloading.

Then proceed to the "mu and mu4e" section below.

mbsync

After this module has been enabled with the +mbsync flag, the steps to set up mbsync are similar to the ones for offlineimap:

Start with writing a ~/.mbsyncrc. Here are some examples:

• For Gmail accounts,
• For Fastmail accounts,
• A more generic example for other services.

The manual page contains all needed information to set up your own.

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

Then proceed to the "mu and mu4e" section below.

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.

Fetching your mail in other ways

Mu4e can be configured to call an arbitary shell command to fetch your email. To use it, set var:mu4e-get-mail-command:

(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 variable (mu4e--get-mail-password-regexp if mu >=1.8) such that doom-package:mu4e will recognize the prompt and let you provide the passphrase from within Emacs.

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 $HOME/.mail

Be sure to replace $HOME/.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! "bar.com"
  '((mu4e-sent-folder       . "/bar.com/Sent Mail")
    (mu4e-drafts-folder     . "/bar.com/Drafts")
    (mu4e-trash-folder      . "/bar.com/Trash")
    (mu4e-refile-folder     . "/bar.com/All Mail")
    (smtpmail-smtp-user     . "foo@bar.com")
    (user-mail-address      . "foo@bar.com")    ;; only needed for mu < 1.4
    (mu4e-compose-signature . "---\nYours truly\nThe Baz"))
  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.

Gmail

With the doom-module:+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 listed here
(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.

Sending mail (SMTP)

Once you're able to fetch your mail, the next step is to configure mu4e to send mail via SMTP. All of the following snippets are meant to be part of your set-email-account! block:

SMTP server configuration

;; In `set-email-account!'
(smtpmail-smtp-user . "foo@bar.com") ; or just 'foo', depending on your provider
(smtpmail-smtp-server   . "smtp.bar.com") ; depends on your provider

Authentication

Most SMTP servers require you to authenticate with your username and a password before sending mail. Emacs will prompt you for this password when you attempt to send mail. You can store this password as described in the relevant info node.

Alternately, if you're already using pass to store your passwords, you can use the doom-module::tools pass +auth module as an auth source. The corresponding entry in your password store should have the same name as your SMTP server (for example, it might be called smtp.bar.com). You may also need to run the function auth-source-pass-enable at some point.

Emacs will first attempt to send mail without supplying credentials, and expects the server to communicate that needs credentials. Some servers (eg. Gmail) will instead abort with an error if they don't recieve credentials on the first attempt. To get around this, you can set smtpmail-servers-requiring-authorization to a regex matching the name of your server:

;; In `set-email-account!'
(smtpmail-servers-requiring-authorization . "smtp\\.bar\\.com")

Gmail

Gmail does not support standard SMTP authentication by default, instead expecting applications to perform OAuth. However, it still supports a much simpler method - it allows you to generate an 'app password', which can be used as a regular SMTP password. You will need to generate an app password in Gmail's settings.

Connection type

Emacs supports three types of SMTP connections: plain (unencrypted, conventionally port 25), ssl (conventionally port 465), and starttls (conventionally port 587). This module defaults to starttls, which is the most modern and recommended option. However, some servers may not support it (you'll usually get a 'connection closed' or 'connection reset' error in this case), or a firewall somewhere in your network may be blocking the port (you'll get a 'network unreachable' error, or similar). In such a case, you may want to change the defaults:

;; In `set-email-account!'
;; example: ssl on port 465
(smtpmail-smtp-service . 465)
(smtpmail-stream-type . ssl)

Sending mail asynchronously

Normally, mu4e will block Emacs while sending mail, which can be annoying when you're on a slow connection and the mail takes a long time to send. There is a workaround in mu4e's manual that uses the doom-package:async library. To use it, you need to include it in your set-email-account! block:

;; In `set-email-account!'
(send-mail-function . async-smtpmail-send-it)
(message-send-mail-function . async-smtpmail-send-it)

If you're using doom-module::tools pass +auth, you also need to ensure that the child Emacs process can access your password-store:

;; This goes OUTSIDE your `set-email-account!' block!
(require 'smtpmail-async)
(add-hook 'async-smtpmail-before-send-hook #'auth-source-pass-enable)

OrgMsg

With the doom-module:+org flag, doom-package:org-msg is installed, and org-msg-mode is enabled before composing the first message. To disable org-msg-mode by default:

;; add to $DOOMDIR/config.el
(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 doom-package: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 alert library.

If you don't like this use:

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

Enabling automatic email fetching

By default, periodic email update is disabled. To enable periodic mail retrieval/indexing, change the value of mu4e-update-interval:

(setq mu4e-update-interval 60)

Troubleshooting

Report an issue?

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.

Sometimes 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:

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

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

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?