Skip to content

OAuth2

Jump to bottom
Javier Callico edited this page Aug 27, 2026 · 1 revision

OAuth2

OAuth2 is supported for Microsoft Outlook/Office 365 and Google Gmail. Configure OAuth instead of an IMAP password for the selected account.

Microsoft

  1. Register an application in Microsoft Entra.
  2. Add delegated IMAP.AccessAsUser.All permission for Office 365 Exchange Online.
  3. Enable public client flows for device-code authentication.
  4. Set the application client ID and, when needed, account type.
SRC_IMAP_PASSWORD=""
SRC_OAUTH2_CLIENT_ID="application-client-id"
SRC_ACCOUNT_TYPE="auto"  # auto, personal, or work

The application uses device-code authentication and does not require a Microsoft client secret.

Google

  1. Create or select a Google Cloud project.
  2. Enable the Gmail API.
  3. Configure the OAuth consent screen.
  4. Create a Desktop application OAuth client.
  5. Set both the client ID and client secret.
SRC_IMAP_PASSWORD=""
SRC_OAUTH2_CLIENT_ID="application-client-id"
SRC_OAUTH2_CLIENT_SECRET="application-client-secret"

Token caching

Persistent caching is controlled with:

OAUTH2_CACHE_ENABLED="true"
OAUTH2_CACHE_DIR=""

Credentials are partitioned by provider, application, and normalized account identity. Persistent storage uses the platform-encrypted MSAL Extensions backend with cross-process locking; plaintext fallback is intentionally prohibited. If encrypted caching is unavailable, the current process continues without persistent storage. See Installation for Linux keyring setup.

Advanced OAuth endpoint overrides in .env.example are intended for testing or specialized deployments and should normally remain empty.

IMAP Migration Tools

Source repository

Clone this wiki locally