OAuth2 Setup Guide

This guide explains OAuth2 authentication concepts and how to set up OAuth2 applications with EmailEngine. For provider-specific instructions, see the dedicated guides for Gmail, Outlook, or Google Service Accounts.

What is OAuth2?

OAuth2 is an authorization framework that allows applications to access user data without requiring passwords. Instead of storing passwords, your application receives temporary access tokens that can be refreshed automatically.

Benefits of OAuth2

Better Security:

• No password storage required
• Tokens can be revoked without changing passwords
• Scoped permissions (request only what you need)
• Works seamlessly with two-factor authentication

Better User Experience:

• Users authenticate directly with their provider (Google, Microsoft)
• Familiar consent screens
• Users can review and revoke access anytime
• No need to share passwords with third parties

Better Compliance:

• Meets modern security standards
• Supports enterprise security policies
• Audit trail of access grants
• Automatic token expiration

OAuth2 Flow Overview

Understanding the OAuth2 flow helps troubleshoot issues:

EmailEngine handles the token exchange and refresh automatically. You just need to:

• Set up the OAuth2 application with the provider (one-time)
• Direct users to the EmailEngine authentication URL
• EmailEngine handles token exchange, storage, and refresh

Supported Providers in EmailEngine

EmailEngine supports OAuth2 for:

Gmail / Google Workspace

Protocol Options:

• IMAP/SMTP with OAuth2 - Standard protocols with OAuth2 authentication
• Gmail API - Native Gmail REST API (faster, more features)

Account Types:

• Internal Apps - Google Workspace organization only
• Service Accounts - Google Workspace with domain-wide delegation
• Public Apps - Any Gmail user (requires security audit)

Gmail IMAP OAuth2 Setup → Gmail API Setup → Google Service Accounts →

Outlook / Microsoft 365

Protocol Options:

• IMAP/SMTP with OAuth2 - Standard protocols with OAuth2 authentication
• Microsoft Graph API - Native Microsoft 365 API

Account Types:

• Single Tenant - Your organization only
• Multi-Tenant - Any Microsoft 365 organization
• Personal Accounts - Outlook.com, Hotmail.com, Live.com
• Combined - Organizations + personal accounts

Outlook OAuth2 Setup →

Setting Up OAuth2 in EmailEngine

Overview of Steps

1. Create OAuth2 app with the provider (Google Cloud Console or Azure AD)
2. Configure consent screen and permissions
3. Get credentials (Client ID and Client Secret)
4. Add to EmailEngine via Configuration → OAuth2
5. Test by adding an account

OAuth2 Application Types

EmailEngine supports different OAuth2 application types:

Gmail:

• Gmail (IMAP/SMTP)
• Gmail API
• Gmail Service Accounts

Outlook:

• Outlook (IMAP/SMTP or MS Graph API)

Each type has its own configuration page in EmailEngine.

Required Information

When configuring OAuth2 in EmailEngine, you'll need:

From Provider (Google/Microsoft):

• Client ID - Identifies your application
• Client Secret - Authenticates your application
• Redirect URI - Where users return after consent

For EmailEngine:

• Application Name - Internal identifier
• Base Scope - Protocol to use (IMAP/SMTP or API)
• Enabled - Whether app shows in authentication forms

Configuration in EmailEngine

Navigate to Configuration → OAuth2 in EmailEngine dashboard.

Add New Application:

1. Click the Add application dropdown and select the provider type (Gmail or Outlook)

2. Fill in the application details:

• Name: Internal identifier (e.g., "Production Outlook")
• Enabled: Check to make available to users
• Client ID: From provider console (Azure AD Application ID or Google Client ID)
• Client Secret: From provider console
• Redirect URL: Your EmailEngine URL + /oauth
• Base Scope: Choose protocol (IMAP/SMTP or MS Graph API)
• Authority (Outlook): Tenant configuration (common, organizations, consumers, or specific tenant ID)

3. Click Register app to save

The application now appears in your OAuth2 configuration list:

Credentials File Upload

Both Google and Microsoft allow downloading credentials as JSON files:

Google credentials file (starts with client_secret_):

{
  "web": {
    "client_id": "123456789.apps.googleusercontent.com",
    "client_secret": "abcdef123456",
    "redirect_uris": ["http://localhost:3000/oauth"],
    ...
  }
}

Microsoft credentials (entered manually):

• Application (client) ID
• Client secret value

EmailEngine can auto-fill fields from Google's JSON file.

OAuth2 Scopes

Scopes define what your application can access.

Gmail Scopes

For IMAP/SMTP:

Scope	Purpose
https://mail.google.com/	Full IMAP and SMTP access (required)

For Gmail API:

Scope	Purpose
gmail.modify	Full Gmail API access (read, write, delete, but not admin functions)

Narrower Scopes (if required by Google):

Scope	Access	Notes
gmail.readonly	Read-only access	Must be combined with gmail.labels (see below)
gmail.send	Send emails only	Cannot read emails
gmail.labels	List and manage labels	Required with gmail.readonly

gmail.readonly requires gmail.labels

The gmail.readonly scope alone cannot list labels (mailboxes). Since EmailEngine requires mailbox information to access emails, you must combine gmail.readonly with gmail.labels for read-only access to work.

Outlook Scopes

For IMAP/SMTP:

Scope	Purpose
IMAP.AccessAsUser.All	Read and manage emails via IMAP
SMTP.Send	Send emails via SMTP (enabled by default)
offline_access	Allow token refresh (required)

If your application doesn't need sending capabilities, you can disable SMTP.Send via the Disabled scopes field in EmailEngine's OAuth2 app settings.

For MS Graph API:

Scope	Purpose
Mail.ReadWrite	Read and manage emails
Mail.Send	Send emails
offline_access	Allow token refresh (required)

offline_access Scope

The offline_access scope allows EmailEngine to refresh access tokens in the background without user interaction.

• Gmail: Enabled by default, no configuration needed
• Outlook: Must be explicitly requested (EmailEngine handles this automatically)

Additional Scopes

You can add extra scopes if you want to use OAuth2 tokens for other APIs:

Example - Add Google Calendar access:

https://www.googleapis.com/auth/calendar

Configure this in Additional scopes field in EmailEngine.

Microsoft Additional Scopes

For Microsoft accounts, additional scopes only work when using MS Graph API as the base scope. If you're using IMAP/SMTP, additional scopes won't be usable because IMAP/SMTP uses the Outlook API, not MS Graph API. You can still add the scopes, but you won't be able to make API requests to those endpoints.

Learn more about using tokens for other APIs →

Disabled Scopes

If Google/Microsoft requires narrower scopes, you can disable the default wide scope:

Disabled scopes field:

https://mail.google.com/

This removes the wide scope from consent requests.

Account Types and Tenant Configuration

Gmail Account Types

Internal Apps:

• Only for Google Workspace organizations
• No security audit required
• Limited to organization's domain

External Apps (Development):

• Limited to 100 manually whitelisted users
• Grants expire after 7 days
• Not suitable for production

External Apps (Production):

• Available to any Gmail user
• Requires thorough security audit (expensive, time-consuming)
• Google may reject broad scopes like https://mail.google.com/

Outlook Account Types

Configure via Supported account types field:

• common - Organizations + personal accounts (most flexible)
• consumers - Personal accounts only (@outlook.com, @hotmail.com)
• organizations - Microsoft 365 organizations only
• <directory-id> - Specific organization only (use Directory/Tenant ID)

Mapping to Azure:

Azure Setting	EmailEngine Value
Any org + personal	common
Personal only	consumers
Any organization	organizations
Single organization	Use Directory ID

Redirect URLs

The redirect URL is where users return after granting consent.

Format

{emailengine-url}/oauth

Examples:

• http://localhost:3000/oauth (development)
• https://ee.company.com/oauth (production)
• https://your-domain.com/oauth (custom domain)

Requirements

• Must be HTTPS in production (HTTP allowed for localhost)
• Must match exactly between provider and EmailEngine
• Case-sensitive
• No trailing slashes
• Must be publicly accessible (for user redirects)

Advanced OAuth2 Features

Authentication Server

Delegate OAuth2 management to an external server:

{
  "authServer": "https://your-auth-server.com/authenticate"
}

Use this when:

• You already manage OAuth2 in your app
• Want centralized token management
• Need custom authentication flows

Learn more about authentication servers →

Pre-filled Email

When generating authentication URLs, you can pre-fill the user's email:

curl -X POST https://your-ee.com/v1/authentication/form \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "email": "user@gmail.com",  // Pre-filled
    "redirectUrl": "https://myapp.com/settings"
  }'

Delegated Access (Shared Mailboxes)

For Microsoft 365 shared mailboxes:

curl -X POST https://your-ee.com/v1/authentication/form \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "shared-support",
    "email": "support@company.com",
    "delegated": true,  // Important
    "redirectUrl": "https://myapp.com/settings"
  }'

Learn more about shared mailboxes →

Service Accounts (Google Workspace)

Access any user's mailbox without individual consent:

{
  "oauth2": {
    "provider": "gmailService",
    "auth": {
      "user": "user@company.com"
    }
  }
}

Requires domain-wide delegation setup.

Learn more about service accounts →