Fetchmail Oauth2 Hell
Summary
This guide describes how to configure fetchmail to work with Outlook.com / Hotmail accounts using OAuth2 authentication.
category Hacking created on 26. October 2025
Begin
This guide explains how to configure Fetchmail to work with Outlook.com or Hotmail accounts using OAuth2 authentication.
It is based on => https://kifarunix.com/install-and-configure-fetchmail-with-oauth2-support-for-request-tracker/ 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 => https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade 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:
The required scopes are:
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:
Generating the Tokens
Run the `fetchmail-oauth2.py` script locally to create the initial authorization code:
Open the displayed URL in your browser, sign in, and grant access.
You will receive an authorization code that starts with something like:
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:
Running Fetchmail as a Daemon
Start Fetchmail as a background service:
This checks for new mail every 35 seconds.
Conclusion
After successful registration and token setup, Fetchmail can access mail securely via OAuth2 without storing plaintext passwords.
The process is painful compared to the standard fetchmail-usage.
Latest article
Dienstagsstammtisch CCCS August
Dienstagsstammtisch CCCS April
Fix for zfs-dkms-git in arch for kernel 5.15.7