Blog

Neomutt + Mutt-wizard + Oauth2 - Apr 14 2025

Introduction

For a good chunk of time I had Neomutt working off of app passwords for both my personal Gmail and Outlook accounts. Eventually, outlook just stopped working, so I wanted to get oauth2 working with Neomutt and add my university email which doesn't allow app passwords. There aren't any complete guides to doing this so here is instructions to get a setup like mine.

Dependencies

Here are the dependencies required for the setup I'm using with links to the packages in the Arch repository or the AUR. It should work if your not on Arch but the packages names can be different or require you to compile+install them on your own.

• isync - sync mail
• cyrus-sasl-xoauth2 - lets isync use xoauth2
• msmtp - sending emails
• pass - password manager
• notmuch - organizes emails
• neomutt - email client
• mutt-wizard - scripts for setting up email

Generating GPG keypair

Make sure you generate a keypair with GPG for pass before doing the next steps

Generating Tokens

microsoft:

This one is easy, we can just use Mozilla Thunderbird's client ID, it doesn't have a client secret so just hit enter when you get the prompt to enter one

client-id: 08162f7c-0fd2-4200-a84a-f25a4db0b584

google:

Unfortunately I couldn't get Thunderbird's client ID to work with google so we are gonna have to create our own. It doesn't cost any money and you can use the client-id for multiple emails, so if its block on one account you can just create them on another.

First, go to gcloud. Then Create a new project and name it something, I made mine just Neomutt.

The UI in gcloud is super confusing so I don't know where this puts you after you create the project. We are looking for this page in API & Services in the Credentials tab.

Then we create an OAuth client ID, it will make you setup some Auth stuff before it lets you make a key but once your done the summary screen should look like this with the information you need on the left.

creating the tokens:

The script to generate/use the tokens is provided by Neomutt. The location is /usr/share/neomutt/oauth2/mutt_oauth2.py in Arch. To generate the token use this command. Use authcode so it gives you a URL to paste into your web browser. For google it will give you a whole setup up screen while with microsoft it will just have your code in the URL.

Once you have the tokens stored somewhere (I put mine in ~/.config/mutt/tokens/) then we can use it to login, fair warning you will need to manually refresh the token when it expires with the command below.

isync - mbsyncrc

Add your email to the mbsyncrc file, its can be in your $HOME folder or your $HOME/.config. You can manual set its location by exporting the MBSYNCRC variable. Make sure your change everything in the {}.

microsoft:

google:

After adding them you can run mbsync -a to fetch the emails, you might need to mkdir if it errors out and can't find the folders. After that you can use mailsync to fetch emails.

msmtp

The config file should be $HOME/.msmtprc or $XDG_CONFIG_HOME/msmtp/config. Add your emails to the list

microsoft:

google:

mutt/accounts

We are manually adding things to mutt-wizard as it doesn't support oauth2 by itself. In your .config/mutt/ you should have a file called muttrc and a folder accounts. The accounts folder will have configs for each one of your emails.

example: accounts/{an email}@outlook.com.muttrc example: accounts/{an email}@gmail.com.muttrc

the mailboxes should be the defaults, but if you have some different setup or encounter some missing mailbox then add it to the list. The names should correspond to the ones in ~/.local/share/mail/{your email}.

mutt/muttrc

It should look like this in your muttrc.

At the end of the 3rd line we want to source a email so it doesn't default to $HOME/Mail

After that then you can add macros so that i + {index} will bring you to a different mailbox

Conclusion

Hopefully this guide works for your setup or at least guides you in the right direction. If anything breaks then I'll try to update this blog post.