OAuth2 Setup Guide

OAuth2 is required for Gmail and Microsoft 365 accounts. This guide covers setup for common providers.

Gmail OAuth2

Step 1: Create Google Cloud Project

Go to Google Cloud Console
Create a new project or select existing
Enable the Gmail API:
- Navigation menu > APIs & Services > Library
- Search for "Gmail API" and enable it

Go to APIs & Services > OAuth consent screen
Select "External" user type
Fill in app information:
- App name: "Mailpilot"
- User support email: your email
- Developer contact: your email
Add scopes:
- https://mail.google.com/ (full Gmail access)
Add your email as a test user

Step 3: Create OAuth Credentials

Go to APIs & Services > Credentials
Create Credentials > OAuth client ID
Application type: Desktop app
Download the JSON file

Step 4: Get Refresh Token

Use the OAuth Playground or a script to get a refresh token:

Option A: OAuth Playground

Go to OAuth 2.0 Playground
Click gear icon > Use your own OAuth credentials
Enter your Client ID and Secret
Select Gmail API v1 > https://mail.google.com/
Authorize APIs
Exchange authorization code for tokens
Copy the refresh token

Option B: Script

# Install oauth2-cli or use any OAuth2 tool
npx oauth2-cli \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --auth-url https://accounts.google.com/o/oauth2/auth \
  --token-url https://oauth2.googleapis.com/token \
  --scope "https://mail.google.com/"

Step 5: Configure Mailpilot

accounts:
  - name: gmail
    imap:
      host: imap.gmail.com
      port: 993
      auth: oauth2
      username: you@gmail.com
      oauth_client_id: ${GMAIL_CLIENT_ID}
      oauth_client_secret: ${GMAIL_CLIENT_SECRET}
      oauth_refresh_token: ${GMAIL_REFRESH_TOKEN}

Microsoft 365 / Outlook OAuth2

Step 1: Register Azure AD Application

Go to Azure Portal
Navigate to Azure Active Directory > App registrations
New registration:
- Name: "Mailpilot"
- Supported account types: Accounts in any organizational directory
- Redirect URI: http://localhost (Web)

Step 2: Configure API Permissions

Go to API permissions
Add permission > Microsoft Graph > Delegated permissions
Add:
- IMAP.AccessAsUser.All
- offline_access
Grant admin consent (if required)

Step 3: Create Client Secret

Go to Certificates & secrets
New client secret
Copy the secret value immediately

Step 4: Get Refresh Token

# Request authorization code
open "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost&scope=https://outlook.office.com/IMAP.AccessAsUser.All%20offline_access"

# Exchange code for tokens
curl -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost" \
  -d "grant_type=authorization_code"

Step 5: Configure Mailpilot

accounts:
  - name: outlook
    imap:
      host: outlook.office365.com
      port: 993
      auth: oauth2
      username: you@company.com
      oauth_client_id: ${OUTLOOK_CLIENT_ID}
      oauth_client_secret: ${OUTLOOK_CLIENT_SECRET}
      oauth_refresh_token: ${OUTLOOK_REFRESH_TOKEN}