mutt integration with Gmail using OAuth

As I mentioned before, I am a heavy terminal user, including viewing and replying emails with it. Mutt is my email client. Once you have setup your 2 factor authentication with Google, you won’t be able to access your Gmail using IMAP with your password, you’ll have to generate a specific password for the so called “Less Secure Apps”. There is a problem with that, if you use IMAP with less-secure-app password on your company account where “less secure app” is not allowed, you are probably stuck.

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 [email protected] --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 = "[email protected]" 
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://[email protected]@smtp.gmail.com:587/"
set from = "[email protected]" 
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!