I am a college student in America where there are unfortunately only two email servers that universities use: Google Workplace Gmail and Microsoft Office 365. Up until this point I’ve used the Office suite without complaints. However, being an average terminal enjoyer, I recently started using a terminal based email client personal email.
Simply changing my email client has transformed the way I deal with email. aerc-mail’s use of vim-esque philosophy for email and the ability to write my emails in neovim has been a real ergonomic and productivity boon. aerc-mail has become my go-to way to email.
You can imagine my disappointment when I realized that how frustrating it is getting a 3rd party email client to work with a university email would be.
But no longer!
After seeing that my university had instructions for using Thunderbird and a few Linux User Group (LUG) Discord messages about using mutt I tried again to make the connection happen. I would like to say thank you b1g_fungus in OSU LUG for giving me some pointers to how get oauth working with mutt.
I will note that the way I have this setup only works for those universities that let their students/staff use Thunderbird. This is because I masquerade as it for oauth purposes.
1. Configuring mutt_oauth2.py to work
Download a copy of mutt_oauth2.py and throw it in your aerc-mail configuration folder.
Update the client_id to be: 9e5f94bc-e8a4-4e73-b8be-63364c29d753 which is
Thunderbird’s client_id.
I would also update GPG settings so that you can keep your tokens encrypted at
rest. I opted to ignore this and replaced the encryption and decryption pipes to
just tee. Now this isn’t ideal as these are live tokens that can be used
on your account to send and receive email. But I couldn’t be bothered to set
this up properly… so tee will have to do.
ENCRYPTION_PIPE = ['tee']
DECRYPTION_PIPE = ['tee']
2. Linking mutt_oauth2.py to aerc-mail
Setup a new account in aerc-mail using :new-account but leave the password
field empty. Now edit the accounts.conf to include the following extra lines
under the account’s header:
source-cred-cmd = "python3 <AERC-CONFIG-FOLDER>/mutt_oauth2.py <AERC-CONFIG-FOLDER>/[email protected]"
outgoing-cred-cmd = "python3 <AERC-CONFIG-FOLDER>/mutt_oauth2.py <AERC-CONFIG-FOLDER>/[email protected]"
Completed it should look something like this:
[University]
source = imaps+xoauth2://username%40university.edu@outlook.office365.com:993
source-cred-cmd = "python3 <AERC-CONFIG-FOLDER>/mutt_oauth2.py <AERC-CONFIG-FOLDER>/[email protected]"
outgoing = smtp+xoauth2://username%40university.edu@smtp.office365.com:587
outgoing-cred-cmd = "python3 <AERC-CONFIG-FOLDER>/mutt_oauth2.py <AERC-CONFIG-FOLDER>/[email protected]"
default = INBOX
cache-headers = true
from = "Last, First" <username@university.edu>
check-mail = 5m # this refreshes the email every 5 minutes
3. Getting a token
Now in your aerc-mail configuration folder open run
python3 mutt_oauth2.py --authorize [email protected]. This will
take you through an interactive setup that will help you get a token. When you
get to the auth flow section, I ended up using authcode but I suggest a bit of
trial and error until you get one that works.
Note some universities block Thunderbird all together so I would suggest starting a conversation with your IT department in getting that approved. After which you can try again.
4. Testing it out
Home stretch now! Now if you run
python3 mutt_oauth2.py [email protected] --test and see no errors
you should be all good to open up aerc-mail and be able to send and receive
email!
I realized after putting this blog post together I probably should have dug around the aerc-mail wiki more because I found the Microsoft provider section but alas it didn’t rank to high in Kagi search.