Let me guess: you were searching for hours trying to figure out how to install Mu4e on macOS. I feel your pain. And you came to the right place. I will try to provide here a complete guide for macOS High Sierra or Mojave on how to install Emacs Mu4e on Mac OS X systems.

Here I am describing how to make it work with Gmail, but with small changes you can make it work with other mail providers.

Perform activities described here at your own peril. During testing mbsync for some reason recreated a bunch of my messages. This is why I recomend to do testing not on your real account. You can change to the real one after everything is set up properly.

Install Homebrew

First of all we need Homebrew. You probably already have it but if you don’t, there is a simple command to get it. Copy the following and paste it to the terminal.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

If you already have Homebrew, just execute the following commands to be sure that we are up to date.

$ brew update
$ brew upgrade

Install Emacs

Then of course we need emacs. You can use built-in version in macOS, but it is pretty old, so I suggest to install the most recent verstion with:

$ brew install emacs

Or if you want a version with graphical interface, use brew install emacs --with-cocoa. I prefer CLI version.

What is next?

First of all let me explain a bit. To comfortably read mail from Emacs you need a several programs:

  1. Emacs itself of course.
  2. mbsync (component of isync). This is the program that will actually fetch emails from your Imap server (for gmail it is imap.gmail.com). The purpose of this program is to syncronize and maintain local email database.
  3. mu. This is a CLI (not Emacs yet) program for reading mail. You have database, but you need something to read it, so you use Mu. Mu lets you easily (and powerfully) search through your emails and find the data you want.
  4. mu4e. This is an Emacs mode, that basically allows you to use Mu inside Emacs.
  5. smtpmail. This is another Emacs mode, that allows you to sends emails to other people (or yourself :)).

Pretty complicated, right? Well, welcome to Emacs.

Installing isync

Installing isync is pretty easy with Homebrew. Just use the following comand:

$ brew install isync

Configuring mbsync

.mbsyncrc

To setup mbsync create a file .mbsyncrc in your home location. For Gmail you can use the following configuration: 

IMAPAccount gmail
Host imap.gmail.com
User <YOUR_ACCOUNT@gmail.com>
PassCmd "gpg -q --for-your-eyes-only --no-tty -d ~/.mbsyncpass.gpg"
Port 993
SSLType IMAPS
AuthMechs Login
CertificateFile /usr/local/etc/openssl/cert.pem

IMAPStore gmail-remote
Account gmail

MaildirStore gmail-local
Path ~/email/gmail/
Inbox ~/email/gmail/INBOX

Channel gmail-inbox
Master :gmail-remote:
Slave :gmail-local:
Patterns "INBOX"

SyncState *

Group gmail
Channel gmail-inbox

Do not forget to change <YOUR_ACCOUNT@gmail.com> to your account at gmail.com.

Install GPG

You will need GPG to encript your password. If you don’t have it, just issue a command for Homebrew:

$ brew install gpg

.mbsyncpass

Then you should create a file containing your password. To make it safer we will encrypt it using GPG.

  1. Create a temprorary file ~/.mbsyncpass with your plain text password inside.
  2. Use the following command to encrypt it with password. 
    $ gpg --output ~/.mbsyncpass.gpg --symmetric .mbsyncpass
  3. Remove .mbsyncpass file.

Mail directories

Create directories for mail databases using following commands:

$ mkdir ~/email
$ mkdir ~/email/gmail

Trying syncronization

To sync all inboxes execute the following command:

mbsync -a

You will be prompted for password, then a syncronization should start:

$ mbsync -a
C: 0/3  B: 0/3  M: +0/0 *0/0 #0/0  S: +0/0 *0/0 #0/0
Maildir notice: no UIDVALIDITY, creating new.
C: 0/3  B: 0/3  M: +0/0 *23/23 #0/0  S: +85/7229 *0/0 #0/0

You can see the current progress S: +85/7229 – that means that 85 emails out of 7229 are processed.

Installing Mu

The next step is to install mu itself. But because of an Homebrew issue you should first install mono. Use the following command:

$ brew install mono

Now you can install mu with Emacs (or mu4e). Use the following command:

$ brew install mu --with-emacs

Unfortunately this installation will not work with Emacs installed from Cask, so I suggest to install Emacs with regular Homebrew, it works perfectly.

Configuring Mu

In a meantime lets check on your syncronization status. Probably a couple more minutes to wait. When it is ready you should let Mu index the mail directory with a following command:

$ mu index --maildir=~/email/gmail/

Then you should set up your Mu4e. Add the following rows to your ~/.emacs file:

(require 'smtpmail)

; smtp
(setq message-send-mail-function 'smtpmail-send-it
      smtpmail-starttls-credentials
      '(("smtp.gmail.com" 587 nil nil))
      smtpmail-default-smtp-server "smtp.gmail.com"
      smtpmail-smtp-server "smtp.gmail.com"
      smtpmail-smtp-service 587
      smtpmail-debug-info t)

(require 'mu4e)

(setq mu4e-maildir (expand-file-name "~/email/gmail"))

(setq mu4e-drafts-folder "/Drafts")
(setq mu4e-sent-folder   "/Sent Mail")
(setq mu4e-trash-folder  "/Trash")

(setq message-signature-file "~/.emacs.d/.signature") ; put your signature in this file

; get mail
(setq mu4e-get-mail-command "mbsync -c ~/.mbsyncrc gmail"
      mu4e-html2text-command "w3m -T text/html"
      mu4e-update-interval 120
      mu4e-headers-auto-update t
      mu4e-compose-signature-auto-include nil)

;; show images
(setq mu4e-show-images t)

;; use imagemagick, if available
(when (fboundp 'imagemagick-register-types)
  (imagemagick-register-types))

;; general emacs mail settings; used when composing e-mail
;; the non-mu4e-* stuff is inherited from emacs/message-mode
(setq mu4e-reply-to-address "<YOUR_ACCONT@GMAIL.COM>"
    user-mail-address "<YOUR_ACCOUNT@GMAIL.COM>"
    user-full-name  "<YOUR FULL NAME>")

Installing W3M

W3M is needed to read HTML messages. To install it use the following command:

$ brew install w3m

Using Mu4e

Finally you are (almost) done! You can try launching Mu4e in Emacs by executing the following command M-x mu4e. If you are lost inside mu4e press q to return back to *mu4e-main*.