Latest articles:

Fetchmail Oauth2 Hell

category Hacking

Begin

This guide explains how to configure Fetchmail to work with Outlook.com or Hotmail accounts using OAuth2 authentication.
It is based on Kifarunix’s guide, but includes several important adjustments for personal Microsoft accounts (@outlook.com, @hotmail.com, etc.).

Using OAuth2 with personal Microsoft accounts can be more complex than with organizational (Entra ID) accounts. The differences below help to avoid common issues with token approval and invalid scopes.

Registering the Application in Azure Portal

Go to the Azure App Registrations Portal.

  • Click “New registration”
  • Choose a name, for example fetchmail-hotmail
  • Under Supported account types, select:

Personal Microsoft accounts only

If you leave the default (“Accounts in any organizational directory”), you may later get an “Admin consent required” or “invalid_scope” error when Fetchmail tries to refresh tokens.

  • Under Redirect URI, select “Web” and enter:

https://login.microsoftonline.com/common/oauth2/nativeclient

This endpoint is supported for local and native authentication flows.

Required OAuth2 Endpoints and Scopes

Use the following endpoints for OAuth2:

Authorization URL: https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize Token URL: https://login.microsoftonline.com/consumers/oauth2/v2.0/token Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient

The required scopes are:

openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send

These scopes allow IMAP and SMTP access for Outlook.com accounts. Do not use https://graph.microsoft.com scopes; they do not provide IMAP or SMTP permissions.

Personally for me IMAP access was good enough.

Example fetchmail-oauth2.cfg for Personal Accounts

Here is an example configuration file adapted for personal Microsoft accounts:

user=<USER>
client_id=<CLIENT_ID>
client_secret=<SECRET_VALUE>

refresh_token_file=/home/airmack/.config/oauth/microsoft/.fetchmail-refresh
access_token_file=/home/airmack/.config/oauth/microsoft/.fetchmail-token

imap_server=outlook.office365.com
smtp_server=outlook.office365.com

scope=openid offline_access https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send
auth_url=https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize
token_url=https://login.microsoftonline.com/consumers/oauth2/v2.0/token
redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient

Generating the Tokens

Run the fetchmail-oauth2.py script locally to create the initial authorization code:

python3 fetchmail-oauth2.py -c ~/.fetchmail-oauth2.cfg --obtain_refresh_token_file

Open the displayed URL in your browser, sign in, and grant access. You will receive an authorization code that starts with something like:

M.C559...

Paste this code into the script when prompted. It will then create and save both refresh_token and access_token at the configured paths.

You can copy these token files to a remote host if Fetchmail runs on a different machine.

Setting Up Automatic Token Refresh

Add a cron job to keep the tokens valid:

*/2 * * * * /home/airmack/code/fetchmail-next/contrib/fetchmail-oauth2.py -c $HOME/.fetchmail-oauth2.cfg --auto_refresh

Running Fetchmail as a Daemon

Start Fetchmail as a background service:

fetchmail -d 35

This checks for new mail every 35 seconds.

Conclusion

Once configured correctly, Fetchmail with OAuth2 works reliably with Hotmail and Outlook.com. However, the setup process is more complex than necessary because Microsoft distinguishes between personal and organizational accounts, requiring separate endpoints and consent handling.

After successful registration and token setup, Fetchmail can access mail securely via OAuth2 without storing plaintext passwords.

created on 26. October 2025