Setting Up Outlook and Microsoft 365

This guide shows you how to set up Outlook OAuth2 authentication with EmailEngine for Outlook.com, Hotmail.com, and Microsoft 365 accounts. You can use either IMAP/SMTP or Microsoft Graph API as the email backend.

Overview

EmailEngine has native support for Outlook and Microsoft 365 accounts with two backend options:

IMAP/SMTP Backend:

• Standard email protocols
• Works like any other email account
• Simpler setup

Microsoft Graph API Backend:

• Native Microsoft 365 integration
• Better performance for high-volume accounts
• Access to Microsoft-specific features
• Supports shared mailboxes natively

This guide covers both options.

Choosing IMAP/SMTP vs MS Graph API

Feature	IMAP/SMTP	MS Graph API
Setup Complexity	Simple	Moderate
Performance	Good	Excellent
Search Capabilities	Full text search	Very limited
Shared Mailboxes	Limited support	Native support
Outlook Categories	Not available	Supported via labels
Connection Protocol	IMAP/SMTP	REST API
Microsoft-Specific Features	Limited	Full access
Works with other providers	Yes	No

MS Graph API Search Limitations

MS Graph API has significantly more limited search capabilities compared to IMAP. IMAP supports full-text search across message headers and body content, while MS Graph API search is much more restricted. If your application requires advanced message search functionality, use IMAP/SMTP instead.

Recommendation:

• Use IMAP/SMTP for simple setups, compatibility, and when you need powerful search capabilities
• Use MS Graph API for shared mailboxes and Microsoft 365 enterprise features (but be aware of search limitations)

Step 1: Create Azure AD Application

Go to Azure Portal and navigate to Microsoft Entra ID → App Registrations.

Click New registration.

Step 2: Configure Application Registration

Application Name

Choose a name that users will see in the authorization form. Make it clear and recognizable (e.g., "EmailEngine" or "YourApp Email Integration").

Supported Account Types

Choose who can use this application:

Personal Microsoft accounts only:

• Only free @hotmail.com, @outlook.com, @live.com accounts
• Select: "Accounts in any organizational directory and personal Microsoft accounts"

Single tenant (organization only):

• Only accounts from your Microsoft 365 organization
• Select: "Accounts in this organizational directory only"

Multi-tenant (any organization):

• Any Microsoft 365 organization account
• Does NOT include personal Microsoft accounts
• Select: "Accounts in any organizational directory"

Multi-tenant + personal accounts:

• Both Microsoft 365 and personal accounts
• Most flexible option
• Select: "Accounts in any organizational directory and personal Microsoft accounts"

Recommended Setting

For maximum compatibility, select "Accounts in any organizational directory and personal Microsoft accounts" unless you have specific requirements.

Microsoft Cloud Environments

EmailEngine supports multiple Microsoft cloud environments beyond the standard commercial cloud:

Cloud	Value	IMAP Host	SMTP Host	Use Case
Commercial	global	outlook.office365.com	smtp.office365.com	Standard Microsoft 365 (default)
GCC High	gcc-high	outlook.office365.us	smtp.office365.us	US Government L4
DoD	dod	outlook-dod.office365.us	outlook-dod.office365.us	US Government L5 (DoD)
China	china	partner.outlook.cn	partner.outlook.cn	China (operated by 21Vianet)

When configuring the OAuth2 application in EmailEngine, select the appropriate cloud environment. EmailEngine automatically uses the correct endpoints for authentication and email access.

Government and Sovereign Clouds

For government clouds (GCC High, DoD) and sovereign clouds (China), you must register your Azure AD application in the corresponding Azure portal for that cloud environment, not the standard Azure portal.

Redirect URI

Platform: Select Web

URI: Your EmailEngine URL with /oauth path:

• http://localhost:3000/oauth (for local testing)
• https://your-emailengine-domain.com/oauth (for production)

Redirect URL Must Match Exactly

The redirect URL must match exactly what you'll configure in EmailEngine later. Mismatches will cause OAuth failures.

Click Register to create the application.

Step 3: Copy Application (Client) ID

On the application overview page, find and copy the Application (client) ID. You'll need this for EmailEngine configuration.

Keep this page open - you'll come back to it.

Step 4: Configure API Permissions

Click API permissions in the left menu.

By default, only User.Read permission exists. Click Add a permission.

Select Microsoft Graph and then Delegated permissions.

For IMAP/SMTP Backend

Add these permissions:

• IMAP.AccessAsUser.All - For IMAP access
• SMTP.Send - For sending emails via SMTP
• offline_access - For token refresh

offline_access Required

The offline_access scope is required in both cases. It allows EmailEngine to renew access tokens in the background without user interaction.

For MS Graph API Backend

Add these permissions instead:

• Mail.ReadWrite - For reading and managing emails
• Mail.Send - For sending emails
• offline_access - For token refresh

Don't Mix Scopes

You cannot use both IMAP/SMTP and Mail.* scopes together. Choose one backend:

• IMAP/SMTP scopes: From Outlook API
• Mail.* scopes: From MS Graph API

Pick one approach and stick with it.

Verify all required permissions are listed, then continue to the next step.

Step 5: Create Client Secret

Click Certificates & secrets in the left menu.

Click New client secret.

Configure Secret

Description: Give it a meaningful name (e.g., "EmailEngine Secret")

Expires: Choose an expiration period you're comfortable with

• 6 months (default)
• 12 months
• 24 months
• Custom

Secret Expiration

When the secret expires, your application will stop working until you generate a new secret and update EmailEngine. Choose a longer expiration for production, but set a reminder to rotate it before expiry.

Click Add.

Copy Secret Value

Copy Secret Now

The secret value is only shown once. Copy it immediately - you cannot retrieve it later. If you lose it, you'll need to generate a new secret.

Copy the value from the Value column (NOT the "Secret ID").

Step 6: Enable IMAP/SMTP (If Using IMAP Backend)

Only for IMAP/SMTP Backend

Skip this step if you're using MS Graph API as your backend.

If you're managing a Microsoft 365 organization and EmailEngine cannot connect via IMAP/SMTP, you may need to enable these protocols manually.

1. Navigate to https://admin.microsoft.com/
2. Go to Users → Active users
3. Select a user
4. Navigate to Mail settings
5. Enable IMAP and SMTP AUTH

You may need to do this for each user or configure organization-wide settings.

Step 7: Configure EmailEngine

Now configure EmailEngine with your Azure application credentials.

Add Outlook OAuth2 Application

1. Open EmailEngine dashboard
2. Navigate to Configuration → OAuth2
3. Click Add application
4. Select Outlook

Configure OAuth2 Settings

Application name: Give it a descriptive name (e.g., "Outlook OAuth2")

Enable this app: Check this box (otherwise it won't appear in authentication forms)

Azure Application Id: Paste the Application (client) ID from Azure

Client Secret: Paste the secret value you copied earlier

Redirect URL: Must match exactly what you entered in Azure:

• Example: http://localhost:3000/oauth

Supported account types: Choose based on your Azure configuration:

• common - Organizations and personal accounts (most flexible)
• consumers - Personal Microsoft accounts only (@hotmail.com, @outlook.com, @live.com)
• organizations - Microsoft 365 organizations only
• <directory-id> - Specific organization only (use Directory/Tenant ID like f8cdef31-a31e-4b4a-93e4-5f571e91255a)

Account Type Mapping

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

Base scope: Select based on your Azure permissions:

• IMAP and SMTP - If you added IMAP.AccessAsUser.All and SMTP.Send
• MS Graph API - If you added Mail.ReadWrite and Mail.Send

Base Scope Must Match Azure Permissions

The base scope you select here must match the permissions you configured in Azure. Mismatches will cause authentication failures.

Click Register app to save.

Step 8: Test the Setup

Add an Outlook account to test the OAuth2 flow.

Via Hosted Authentication Form

1. In EmailEngine, click Add account
2. Click Sign in with Microsoft
3. Complete the OAuth2 consent flow
4. EmailEngine will store the credentials and connect

The account should enter "connected" state within moments.

Via API

Generate an authentication form URL:

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

Direct the user to the returned URL.

Learn more about hosted authentication →

Direct API Account Registration

If you already have OAuth2 tokens:

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "name": "John Doe",
    "email": "user@outlook.com",
    "oauth2": {
      "provider": "AAABlf_0iLgAAAAQ",
      "accessToken": "EwBIA8l6...",
      "refreshToken": "M.R3_BAY..."
    }
  }'

Provider ID

The provider field should be the OAuth2 application ID from EmailEngine, which is a base64url encoded string like AAABlf_0iLgAAAAQ. You can find this ID in Configuration → OAuth2 Apps in the EmailEngine interface. This is NOT the Application (client) ID from Azure AD.

See full API documentation →

Shared Mailboxes

Microsoft 365 shared mailboxes are mailboxes not bound to a specific user. Multiple users can access them using their own credentials.

EmailEngine supports shared mailboxes through two approaches:

• Direct access - Add shared mailbox with its own OAuth2 credentials
• Delegated access - Add main account, then reference it for shared mailboxes (recommended)

For detailed setup instructions, see the Shared Mailboxes guide →

Performance Considerations

IMAP/SMTP Limits

Microsoft enforces connection and rate limits:

Connection Limits:

• 15 concurrent IMAP connections per account
• 30 SMTP connections per minute

Rate Limits:

• Throttling on excessive operations
• May temporarily block account

Best Practices:

• Use sub-connections sparingly
• Implement path filtering
• Monitor account states for throttling

MS Graph API Limits

Microsoft Graph has separate quotas:

Throttling Limits:

• Varies by license type and tenant
• Typically higher than IMAP limits

Best Practices:

• Implement exponential backoff
• Use batch requests where possible
• Monitor for throttling responses

Learn more about performance tuning →

Production Considerations

Admin Consent for Organization Apps

For single-tenant or organization apps, an admin can grant consent for all users:

1. In Azure AD, go to your app registration
2. Click API permissions
3. Click Grant admin consent for [Organization]

This pre-approves the app for all users in the organization.

Token Management

EmailEngine automatically:

• Refreshes access tokens when they expire during API requests
• Makes regular API requests (at least daily) even for idle accounts, keeping refresh tokens active
• Stores refresh tokens securely
• Re-authenticates on token failures

You can:

• Retrieve current access tokens for other Microsoft API calls
• Monitor token status via account state
• Revoke access by deleting the account

Refresh Token Expiration

Microsoft refresh tokens can expire under certain conditions:

• 90 days of inactivity - If not used to obtain new access tokens
• Maximum ~1 year - Rolling lifetime limit even if used regularly (may vary by tenant configuration)
• User revokes consent - Via https://myapps.microsoft.com
• Admin revokes app - Via Azure AD Enterprise Applications
• Password change - Invalidates existing refresh tokens
• Policy changes - New MFA or conditional access policies invalidate old tokens
• "Sign out everywhere" - User action that kills all refresh tokens

EmailEngine keeps tokens active by making regular API requests, but if an account is deleted from EmailEngine and re-added later, a new consent flow is required.

Client Secret Expiration

Microsoft OAuth2 client secrets expire (90 days to 2 years max). When expired, all accounts using that OAuth2 app fail immediately. Monitor expiration dates in Azure AD and rotate secrets before they expire.

Learn more about OAuth2 token management →