Microsoft 365 OAuth2 Configuration Guide

Send emails via Microsoft 365 using OAuth2 — no passwords, no Basic Auth. Follow this guide exactly to avoid common pitfalls.

Prerequisites

Part 1

Azure Portal Setup

Step 1 — Register Your App

  1. Go to portal.azure.com
  2. Navigate to Azure Active Directory -> App Registrations -> New Registration
  3. Enter any name (e.g. My Mailer)
  4. Select Single tenant only (Accounts in this organizational directory only)
  5. Click Register

Step 2 — Collect Your Credentials

From the App Registration overview page, copy and save:

Step 3 — Create a Client Secret

  1. Go to Certificates & Secrets -> New Client Secret
  2. Set expiry to 24 months (recommended)
  3. Copy the Value immediately
⚠️ The secret disappears permanently after you leave the page. Copy it before navigating away!

Step 4 — Add API Permissions

  1. Go to API Permissions -> Add a Permission
  2. Select Office 365 Exchange Online -> Application Permissions -> add SMTP.SendAsApp
  3. Click "Grant admin consent for [your org]" and confirm
Part 2

Exchange Online Setup

⚠️ Most people miss this! Azure AD permissions alone are NOT enough for SMTP. Exchange Online needs its own separate configuration — skipping this causes 535 5.7.3 Authentication Unsuccessful.

Step 5 — Get Your Enterprise Application Object ID

⚠️ This is NOT the same as the App Registration Object ID. Using the wrong one will fail.
  1. Go to Azure Active Directory -> Enterprise Applications
  2. Search your app name and click it
  3. Copy the Object ID shown here
LocationObject ID typeUse?
App Registrations -> your app App Registration Object ID ❌ Wrong
Enterprise Applications -> your app Enterprise Application Object ID ✅ Correct

Step 6 — Run PowerShell Commands

💡 No PowerShell? Use Azure Cloud Shell in your browser. Select PowerShell mode — ExchangeOnlineManagement is pre-installed, skip the install step.

Windows — Open PowerShell as Administrator:

Install-Module -Name ExchangeOnlineManagement

Linux / Mac:

# Ubuntu/Debian
sudo apt-get install -y powershell

# Fedora/RHEL
sudo dnf install -y powershell

# Any distro via snap
sudo snap install powershell --classic

pwsh   # launch PowerShell

Connect to your tenant (browser popup — sign in as Global Admin):

Connect-ExchangeOnline -Organization YOUR_TENANT_ID

Register your app as an Exchange Service Principal:

New-ServicePrincipal -AppId YOUR_CLIENT_ID -ObjectId YOUR_ENTERPRISE_APPS_OBJECT_ID

Copy the ObjectId from the output — this is your Service Principal ID.

Grant mailbox access:

Add-MailboxPermission -Identity "yourmail@yourtenant.onmicrosoft.com" -User YOUR_SERVICE_PRINCIPAL_ID -AccessRights FullAccess
Part 3

Application Configuration

FieldValue
From Emailyourmail@yourtenant.onmicrosoft.com
Client IDFrom Step 2
Client SecretFrom Step 3
Tenant IDFrom Step 2

🔧 Common Errors & Fixes

ErrorCauseFix
535 5.7.3 Authentication Unsuccessful Exchange Service Principal not registered Complete Part 2 fully
535 5.7.3 even after Part 2 Wrong ObjectId used Redo Step 5 using Enterprise Applications Object ID
550 5.7.501 Spam abuse detected Trial tenant IP reputation issue Use a paid M365 subscription or raise a Microsoft support ticket
Token fetch fails Wrong OAuth2 scope Scope must be https://outlook.office365.com/.default
XOAUTH2 not supported Missing auth mechanism config Set mail.smtp.auth.mechanisms=XOAUTH2
Client secret not working Secret expired or copied incorrectly Generate a new secret and copy it immediately

⚙️ How It Works

OAuth2 Client Credentials Flow — designed for server-to-server communication. No manual login required, no passwords over the wire, only short-lived tokens that auto-refresh silently.

  1. App fetches a short-lived OAuth2 token from Azure AD using Client ID + Secret
  2. App connects to smtp.office365.com:587 with STARTTLS
  3. App authenticates via XOAUTH2 — token, not password
  4. Exchange verifies token, Service Principal, and Mailbox Permission
  5. Email delivered!