A Linux IMAP and SMTP example with Oauth2 to O365

Assembled by Márton Balázs, IT rep for Maths
last updated: [2025-04-12]

This is a tested example of reading emails via IMAP and sending via SMTP to O365 using Oauth2 authentication. It is using isync for getting email locally, NeoMutt for reading from file and sending via msmtp. Hopefully the below will make sense with other clients as well. Notice that IMAP and SMTP access is turned off by default at the UoB, you can request this with IT Services.

1. Install cyrus-sasl-xoauth2 (it might as well be a package, like it is in Arch AUR). On Ubuntu 20.04 some tweaks are needed:
   1. Install the libsasl2-dev package, otherwise cyrus-sasl-xoauth2 will complain.
   2. When following the cyrus-sasl-xoauth2 instructions, after autogen.sh and configure, but before make and make install, find the line

            pkglibdir = ${CYRUS_SASL_PREFIX}/lib/sasl2
           

      in Makefile, and change it to

            pkglibdir = ${CYRUS_SASL_PREFIX}/lib/x86_64-linux-gnu/sasl2
           

      (source of wisdom).
   3. If you had isync installed (see below) then reinstall it so that it notices the new sasl plugin.
2. Install oauth2ms. Its config file is in ~/.config/oauth2ms/config.json:

   {
   	"tenant_id": "<see your ITS' guides>",
   	"client_id": "<see your ITS' guides>",
   	"client_secret": "",
   	"redirect_host": "localhost",
   	"redirect_port": "5000",
   	"redirect_path": "/appredirecturi/",
   	"scopes": ["https://outlook.office.com/IMAP.AccessAsUser.All", " https://outlook.office.com/SMTP.Send"]
   }

   where tenant_id and client_id are to be provided by your IT Services. Click here for the UoB ones. I suspect that redirect_port is irrelevant but cannot be left empty.
   
   The first time you run oauth2ms it will guide you through getting a token, see the details on their GitHub page. The token is stored in ~/.local/share/oauth2ms/credentials.bin, make sure the disk or this part of your filesystem is encrypted. Alternatively, the token can be encrypted with the -e option.
   
   From time to time you'll be thrown loads of errors. Remove the token and let oauth2ms regenerate it.
   
   (Oauth2ms works fine on Ubuntu 20.04; at home on Arch I now use oama, which is also a package in Arch/AUR. Following their instructions was straightforward, but the "device code flow" method didn't work, I use "other authorization flows".)
3. You can use isync for downloading emails. Make sure your filesystem is encrypted. The relevant parts of ~/.mbsyncrc:

   IMAPAccount uob
   PipelineDepth 1
   # Address to connect to
   Host outlook.office365.com
   User ab12345@bristol.ac.uk
   PassCmd oauth2ms
   AuthMechs XOAUTH2
   SSLType IMAPS
   CertificateFile /etc/ssl/certs/ca-certificates.crt
   Timeout 180

   of course write in your UoB userid.
4. Install msmtp. At the time of writing this, Ubuntu 20.04 has version 1.8.6-1, while at least 1.8.13 is needed; in the office I'm using Davmail instead. The relevant parts of its config file ~/.msmtprc:

   defaults
   protocol smtp
   tls on
   tls_trust_file /etc/ssl/certs/ca-certificates.crt
   
   account uob
   host smtp.office365.com
   port 587
   auth xoauth2
   from x.yzuv@bristol.ac.uk
   user ab12345@bristol.ac.uk
   passwordeval oauth2ms

   of course write in your public email address and UoB userid.
5. I use NeoMutt, here is the relevant bit of ~/.mutt/muttrc (or the sub-config you link in there):

   set realname = 'xab yzuv'
   set from = x.yzuv@bristol.ac.uk
   unset smtp_url
   unset smtp_pass
   set sendmail = "/usr/bin/msmtp -a uob"

   again, set your real name and public email address.