How to Configure Fetchmail with OAuth2 for Gmail: 2026 Guide

by

If you’ve recently tried using Fetchmail with Gmail and encountered authentication errors, the reason is simple:

Google now mandates OAuth2 for nearly all IMAP/POP3 connections, phasing out support for “Less Secure Apps” and even standard App Passwords in many scenarios.

Configuring OAuth2 in Fetchmail requires an extra step, obtaining an Access Token, but it ensures your local server continues to collect emails with the maximum security level required in 2026.

1. Creating Credentials in Google Cloud Console

Before touching your Linux configuration, you need to “authorize” your server within the Google ecosystem:

  1. Access the Google Cloud Console and create a new project.
  2. Go to APIs & Services > Library and enable the Gmail API.
  3. Under OAuth Consent Screen, set it to “External” and add your email as a test user.
  4. Go to Credentials > Create Credentials > OAuth Client ID. Select “Desktop App” and take note of your Client ID and Client Secret.

2. Generating the Refresh Token

Since Fetchmail cannot open a browser for you to log in, we use helper scripts like fetchmail-oauth2.py (available in the official Fetchmail repository) to generate a permanent Refresh Token.

# Example command to generate the token:
python3 fetchmail-oauth2.py --client_id=YOUR_ID --client_secret=YOUR_SECRET --refresh_token_file=.fetchmail-gmail-token

Follow the link that appears in your terminal, log in to your Gmail account, and paste the verification code back into the script.

3. Configuring .fetchmailrc for OAuth2

Now, instead of a password, Fetchmail will use the OAUTH2 protocol and the token you generated. Edit your .fetchmailrc file:

poll imap.gmail.com
    protocol imap
    user "your-email@gmail.com"
    # Instead of a password, we use the modern authentication directive:
    auth oauth2
    password "PASTE_YOUR_REFRESH_TOKEN_CONTENT_HERE"
    ssl
    sslcertck
    is "local-user" here

💡 Admin Pro Tip: Why OAuth2?

Many sysadmins resist OAuth2 because it’s more complex to set up. However, the advantage is clear: you won’t need to update your server settings if you change your main Google password. Furthermore, if your server is compromised, you can revoke just that specific token via Google’s panel without exposing your primary credentials.

Conclusion

Setting up OAuth2 for Fetchmail is a necessary evolution to maintain compatibility with modern email ecosystems.

Once configured, the system remains extremely stable and secure for local mail management.

Struggling with the token generation script or facing ‘Authentication Failed’ errors? Leave a comment below and let’s debug it together!

Leave a Comment