In this tutorial, I am going to show you how to setup the Google recommended OAuth 2.0 way with Mutt.

Remember, the OAuth client setup should be an one-time step, it should be usable for your different email addresses on Gmail, that includes your work email if your employer choose Gmail as their email service provider, as long as you authorize permission during the OAuth App.

1. Login to your google account, navigate to https://console.cloud.google.com/apis/credentials and if this page says anything API not enabled, enable it.
2. In the credentials page, create a project.
3. After creating the project, you should be able to go to the OAuth consent screen tab, put something recognizable in the application name, click save.
4. Go back to “Credentials” page and click on “Create credentials” button and select OAuth client ID.
5. Select other and click create. You’ll be given an OAuth client ID and secret. You can view the id and secret anytime.

Now you’ve setup an OAuth client, it is time for mutt configuration.

Download oauth2.py from GitLab: https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py and make it executable. You’ll need to run the command to generate an OAuth token.

Fill your Google App client id and secret here: https://gitlab.com/muttmua/mutt/-/blob/5347d1c5c0f529ad7e1464ce9f1716d54ed9c31a/contrib/mutt_oauth2.py#L61 and Line 62.

Execute the following command to authorize yourself.

mutt_oauth2.py userid@myschool.edu.tokens --verbose --authorize

Open the web browser with the link given and authenticate yourself, login and grant permission.

The way I manage my files under ~/.mutt:

.
|-- accounts
|   |-- gmail.asc
|   |-- account2.asc
|   |-- account3.asc
|-- mailcap
|-- muttrc
|-- oauth2.py
...

The muttrc master config file only manage generic stuff such as header and format stuff, it also has some macro to map function keys to switch accounts. The actual accounts are under ~/.mutt/accounts folder with GPG encryption in ASCII.

The original gmail file should only contain account related stuff, such as IMAP and SMTP configuration. At the core the login lines should be:

set imap_user = "your@gmail.com" 
set imap_authenticators="oauthbearer"
set imap_oauth_refresh_command="~/.mutt/mutt_oauth2.py ~/.mutt/tokens/gmail"
set smtp_authenticators="oauthbearer"
set smtp_oauth_refresh_command="~/.mutt/mutt_oauth2.py ~/.mutt/tokens/gmail"
set smtp_url = "smtp://your@gmail.com@smtp.gmail.com:587/"
set from = "your@gmail.com" 
set realname = "Your Name"
set signature = "~/.mutt/signatures/mysig"

# Basic config, you can leave this as is 
set folder = "imaps://imap.gmail.com"
set spoolfile = "+INBOX"
set imap_check_subscribed 
set postponed = "+[Gmail]/Draft"
set record = ""
set header_cache=~/.mutt/cache/headers

You should be able to use mutt to view/send emails via Gmail using OAuth 2.0!

It is nearly a year that I haven’t used Windows as my in-production OS, instead I’ve used either RedHat sponsored Linux distro (Fedora) or a RHEL-copy CentOS.

sudo yum install mutt

Now it is the fun part.

By default, your mutt will read info from ~/.muttrc or ~/.mutt/muttrc. Since I have several email addresses needed to be setup, I use the second one.

mkdir -p ~/.muttrc/accounts

Which creates requested folders.

Go to ~/.mutt/accounts/ and create your email account file (you may name it as your like, but keep track of the file name) like the following way:

# Uni Email Setting, file name: university
set from = "abcdef@esp.tld"
set realname = "Your Name Here"
# IMAP settings here
set imap_user = "abcdef"
set imap_pass = ""       # Password is empty here so you'll key-in passwords everytime you wish to access your email account
set folder = "imaps://imap.mail.tld:993"
set spoolfile = "imaps://imap.mail.tld:993/Inbox"   # For gmail users, you need to set your spoolfiles to "+INBOX"
set imap_check_subscribed
set mime_forward=yes
set mime_forward_rest=yes

#SMTP settings
set smtp_url = "smtp://abcdef@smtp.esp.tld:587/"
set smtp_pass = ""

set mail_check = 120
set timeout = 300
set imap_keepalive = 300
# You can set the postponed/record to "+Drafts" or "Sent" correspondently below.
set postponed = "imaps://imap.mail.tld:993/Inbox.Drafts"
set record = "imaps://imap.mail.tld:993/Inbox.Sent"
set header_cache=~/.mutt/cache/headers

You can also put your GnuPG keys under your account if you have multiple keys for multiple emails for some reason. You need to copy the content over under each of your account setting. Remember to substitute your public key identifier in the config files.

You can create similar ones with gmail, assume that you have read the comments above.

Now we put some general information into our muttrc:

vim ~/.mutt/muttrc

set editor = "vim"
set header_cache=~/.mutt/cache/headers
set message_cachedir=~/.mutt/cache/bodies
set certificate_file=~/.mutt/certificates
set move = no
set include
set sort = 'threads'
set sort_aux = 'reverse-last-date-received'
set auto_tag = yes
ignore "Authentication-Results:"
ignore "DomainKey-Signature:"
ignore "DKIM-Signature:"
alternative_order text/plain text/html *
auto_view text/html
bind editor  complete-query
bind editor ^T complete
bind editor  noop
set hostname = desktop.luxing.im
set sig_on_top = yes

# Create a statusbar shows the information in localtime.
set pager_format="%4C %Z %[!%b %e at %I:%M %p]  %.20n -- %s%* -- (%P)"

# Accounts and Shortcuts
source ~/.mutt/accounts/acadia
macro index  'source ~/.mutt/accounts/yeah!'
macro index  'source ~/.mutt/accounts/126!'


# move spam to Spam/ from: http://chrisjrob.com/2011/03/23/configuring-mutt-for-spam/
macro index S "unset resolveNset resolve=INBOX.Spam" "file as Spam"
macro pager S "=INBOX.Spam" "file as Spam"

macro index H "unset resolveNset resolve=INBOX" "file as Ham"
macro pager H "=INBOX" "file as Ham"

# return to inbox by pressing .
macro index . "=INBOX" "Inbox"

set pager_format="%4C %Z %[!%b %e at %I:%M %p]  %.20n  %s%* -- (%P)" # show the corresponding local time of the email.
set pgp_use_gpg_agent = yes

You need to adjust your accounts corresponding to your settings.

If you put sensitive information like your passwords into your account, remember to chmod 600 for security concern.