This is a guide to setting up access to email from a Gmail account (eg: within Emacs (Doom Emacs) using notmuch (a) and lieer (a).

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


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

Required Software

  1. lieer

    git clone
    cd lieer
    pip3 install -r requirements.txt
  2. notmuch

    sudo apt install notmuch

Create an OAuth2 Client ID

  1. Please refer to: Create an OAuth2 Client ID
  2. Ensure GMail APIs are enabled for this Client ID.
  3. Download the JSON format of this key.

Enable notmuch within emacs

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

  1. Enable notmuch by uncommenting notmuch within init.el beneath the :email header.
  2. Run doom sync in your shell.
  3. Reload doom emacs by either killing emacs and restarting, or by running doom/reload (SPC : doom/reload or SPC h r r).

Configure notmuch

These steps are pulled from notmuch’s own documentation (a).

  1. Run notmuch in your shell to create ~/.notmuch-config.

  2. Perform initial indexing:

    # Create a directory to house your mail if you don't already have one.
    mkdir -p /path/to/your/mail/directory
    cd /path/to/your/mail/directory
    notmuch new

    You should see something like:

    Found 0 total files (that's not much mail)
    No new mail.

Configure lieer

These steps are pulled from lieer’s own documentation (a).

  1. Make a directory for the lieer storage and state files (local repository).

    cd /path/to/your/mail/directory
    mkdir <you>.gmail
  2. Update your ~/.notmuch-config to ignore json, lock, and bak files by updating the [new] section to read:

  3. Initialize your mail storage.

    This command will open a new tab in your browser. We need to run this command once before we can specify our own credentials. Feel free to close the tab as soon as it opens as we’ll be swapping the default client id with our own in the next steps.

    # From within /path/to/your/mail/directory/<you>.gmail
    /path/to/lieer/gmi init <you>
  4. Cancel out (CTRL-C).

    You should see a message similar to:

    init: repository is set up, but authorization failed. re-run 'gmi auth' with proper parameters to complete authorization
  5. Set your credentials.

    # From within /path/to/your/mail/directory/<you>.gmail
    /path/to/lieer/gmi auth \
    # Or, if you're working remotely (SSHing into your workstation, etc)
    /path/to/lieer/gmi \
      --noauth_local_webserver \
      auth \

    Open the link and authenticate using your account. Copy the code and paste it back into the running gmi command. You should see a message like:

    Authentication successful.
    credentials stored in /path/to/your/mail/directory/
  6. Sync your email.

    This step may take a long time. My initial sync of 90k emails took 56 real-time minutes.

    # From within /path/to/your/mail/directory/<you>.gmail
    /path/to/lieer/gmi sync

Sync emails periodically

You could also use a systemd timer for this.

  1. Create a new shell script to sync your email. Remember to chmod 777!

    cd /path/to/your/mail/directory/
    /path/to/lieer/gmi sync
  2. Configure the cronjob with crontab -e.

    # Sync email with lieer every three minutes.
    */3 * * * * bash /path/to/your/script/

Configure notmuch within emacs (optional)

  • Set up saved searches (a).

  • Prevent wrapping text at 70 characters while composing an email:

    ;; This is valid in doom emacs. You may need to customize for other distributions.
    ;; Prevent wrapping at 70 characters in email composition.
    (add-hook! 'message-mode-hook 'turn-off-auto-fill)
    (add-hook! 'message-mode-hook 'visual-line-mode)


For those of you using doom emacs (a), you can open notmuch from anywhere with SPC o m.