This is a guide to setting up access to email from a Gmail account (eg: within Emacs (Doom Emacs) using mu, mbsync (isync), and mu4e (mu for emacs).

You may have to complete additional steps if you are not using doom emacs (a), Gmail, or if your set-up differs from mine in other ways.


Please be sure you’ve completed these steps before continuing:

Required Software

  1. Install mbsync version >= 1.4.1.

    We will use mbsync to download our email. It is essential that the version is greater than or equal to 1.3.3 to ensure the OAuth2 token is not cut off (see line 1891 in drv_imap.c (a))

    git clone isync
    cd isync
    sudo make install
  2. Install mu.

    mu will index the emails we’ve downloaded with mbsync and provide them to the mu4e package.

    sudo apt install maildir-utils
  3. Install mu4e.

    mu4e is our email client within emacs.

    sudo apt install mu4e
  4. Download gmail-oauth2-tools.

    This utility will generate our refersh tokens for us.

    git clone
  5. Download Cyrus SASL Oauth2

    mbsync doesn’t support OAuth2, so we’ll install a plugin which enables it.

    # Reference:
    # Clone the Cyrus SASL OAuth2 sources.
    git clone
    # Configure and make.
    cd cyrus-sasl-xoauth2
    # SASL2 libraries on Ubuntu are in /usr/lib/x86_64-linux-gnu/; modify the Makefile accordingly
    sed -i 's%pkglibdir = ${CYRUS_SASL_PREFIX}/lib/sasl2%pkglibdir = ${CYRUS_SASL_PREFIX}/lib/x86_64-linux-gnu/sasl2%' Makefile
    sudo make install
    # Install saslpluginviewer
    sudo apt install sasl2-bin
    # Verify XOAUTH2 is known to SASL.
    saslpluginviewer | grep XOAUTH2

Create an OAuth2 Client ID

Please refer to: Create an OAuth2 Client ID

Create mbsyncrc

  1. Create a new file at ~/.mbsyncrc (or symlink to that location, etc).
  2. Base your config on mine, included below:
    # Account Information
    IMAPAccount gmail
    AuthMechs XOAUTH2
    PassCmd "/path/to/"
    IMAPStore gmail-remote
    Account gmail
    MaildirStore gmail-local
    Path ~/.mail/cashweaver-gmail
    Inbox ~/.mail/cashweaver-gmail/inbox
    Channel gmail-inbox
    Far :gmail-remote:
    Near :gmail-local:
    Patterns "INBOX"
    Channel gmail-sent
    Far :gmail-remote:"[Gmail]/Sent Mail"
    Near :gmail-local:sent
    Remove Near
    Create near
    SyncState *
    Channel gmail-trash
    Far :gmail-remote:"[Gmail]/Trash"
    Near :gmail-local:trash
    Remove Near
    Create near
    SyncState *
    Channel gmail-drafts
    Far :gmail-remote:"[Gmail]/Drafts"
    Near :gmail-local:drafts
    Remove Near
    Create near
    SyncState *
    Group gmail
    Channel gmail-inbox
    Channel gmail-sent
    Channel gmail-trash
    Channel gmail-drafts

Emable IMAP in your Gmail Account

Follow the documentation (a) to enable IMAP.

Enable mu4e within emacs

This step is written for those using doom emacs (a). Those using other flavors of emacs will need to enable mu4e on their own.

  1. Enable mu4e within doom emacs (a) by uncommenting (mu4e +gmail) within init.el.

  2. Sync doom emacs.

    doom sync
  3. Reload doom emacs by either killing emacs and restarting, or by running doom/reload (SPC : doom/reload or SPC h r r).

Sync and index your email

Follow the steps documented by doom emacs’ mu4e section (a).

  1. Sync your email by running mbsync --all.

    This may take a while.

  2. Index your email by running:

    mu init --maildir ~/.mail --my-address <you>
    mu index
  3. Configure emacs to use your email address.

    As an example:

    ;; Each path is relative to `+mu4e-mu4e-mail-path', which is ~/.mail by default
    (set-email-account! ""
                        '((mu4e-sent-folder       . "/ Mail")
                        (mu4e-drafts-folder     . "/")
                        (mu4e-trash-folder      . "/")
                        (mu4e-refile-folder     . "/ Mail")
                        (smtpmail-smtp-user     . "<you>")
                        (mu4e-compose-signature . "<Your signature here>"))