Configuring Gmail and Outlook365 on Neomutt

2025.03.18 | tags: tutorials

Gmail

First enable two-factor authentication on your Google account settings, and then create an application password for Neomutt.

Once you have the app password, you can store it in your password manager (or expose it in plain-text). I personally use pass, which is what my example configurations below also use:

$ pass add gmail

Create ~/.config/mutt/yourname@gmail.com [1]:

set from = "Your Name <yourname@gmail.com>"
set realname = "Your Name"
set imap_user = "yourname@gmail.com"

set smtp_url = "smtps://yourname@gmail.com@smtp.gmail.com:465/"
set folder = "imaps://imap.gmail.com:993/"

set smtp_authenticators = "gssapi:login"
set ssl_starttls = yes
set ssl_force_tls = yes

set my_pass = "`pass gmail`"
set imap_pass = $my_pass
set smtp_pass = $my_pass

set spoolfile = "+INBOX"
set record = "+[Gmail]/Sent Mail"
set postponed = "+[Gmail]/Drafts"
set trash = "+[Gmail]/Trash"

mailboxes =INBOX ="[Gmail]/Sent Mail" =[Gmail]/Drafts =[Gmail]/Spam =[Gmail]/Trash

Source the email configuration in ~/.config/mutt/muttrc:

source ~/.config/mutt/yourname@gmail.com
folder-hook "yourname@gmail.com" "source ~/.config/mutt/yourname@gmail.com"

Outlook365

Add your Outlook password to your password manager:

$ pass add outlook

Generate an OAuth2 token [2]. The client-id we are using here is Thunderbird’s:

$ /usr/local/share/neomutt/oauth2/mutt_oauth2.py \
	-v \
	-t \
	--authorize \
	--client-id "9e5f94bc-e8a4-4e73-b8be-63364c29d753" \
	--client-secret "" \
	--email "yourname@outlook.com" \
	--provider microsoft \
	~/.config/mutt/outlooktoken

When prompted, choose authcode as the “OAuth2 flow”. As for “client secret”, leave it empty. The script should then point you to a URL which will take you to the Outlook365 login page. Onced logged in, you will be redirected to a URL which includes the authorization code needed by the script. Because it might be hard to filter out the code by hand, you can copy the whole URL and run the following command to get the code:

$ echo "the_url" | sed 's/.*code=//;s/\&.*//'

Paste the output of this command to the script prompt when asked, and press enter.

Create ~/.config/mutt/yourname@outlook.com [1]:

set from = "Your Name <yourname@outlook.com>"
set realname = "Your Name"
set imap_user = "yourname@outlook.com"

set smtp_url = "smtp://yourname@outlook.com@smtp.office365.com:587"
set folder = "imaps://yourname@outlook.com@outlook.office365.com"

set smtp_authenticators = "xoauth2"
set imap_authenticators = "xoauth2"
set ssl_starttls = yes
set ssl_force_tls = yes

set my_pass = "`pass outlook`"
set imap_pass = $my_pass
set smtp_pass = $my_pass

set imap_oauth_refresh_command = "/usr/local/share/neomutt/oauth2/mutt_oauth2.py ~/.config/mutt/outlooktoken"
set smtp_oauth_refresh_command = "/usr/local/share/neomutt/oauth2/mutt_oauth2.py ~/.config/mutt/outlooktoken"

set spoolfile = "+INBOX"
set record = "+Sent Items"
set postponed = "+Drafts"
set trash = "+Deleted Items"

mailboxes =INBOX ="Sent Items" =Drafts ="Deleted Items"

Source the email configuration in ~/.config/mutt/muttrc:

source ~/.config/mutt/yourname@outlook.com
folder-hook "yourname@outlook.com" "source ~/.config/mutt/yourname@outlook.com"

Notes

  1. If you want to add more mailboxes, you can append them to mailboxes like so: =MailboxName.
  2. The paths for mutt_oauth2.py might differ depending on the operating system. For example, on FreeBSD it’s /usr/local/share/neomutt/oauth2/mutt_oauth2.py, but on Linux, it’s usually /usr/share/neomutt/oauth2/mutt_oauth2.py.