Sending Email (SMTP OAuth2) — FAQ for Application Teams & Developers

Quick Summary

• Protocol: SMTP AUTH with OAuth2 (AUTH XOAUTH2) to smtp.office365.com (port 587, STARTTLS).
• Preferred: Delegated permissions (user present) with scope https://outlook.office.com/SMTP.Send.
• Exception: App-only requires SMTP.SendAsApp and an Exchange service principal registered & scoped to the specific mailbox(es).
• Mailbox: Use a service/shared mailbox (request via the Help Desk process), and ensure Authenticated SMTP is enabled for that mailbox.

Timeline: Dartmouth retires SMTP Basic Auth in September 2025. After that, sending must use OAuth2.

Who Does What?

Flows

Delegated (Preferred)

• Scope: https://outlook.office.com/SMTP.Send (plus offline_access if you need refresh tokens).
• Acquire a delegated token (Auth Code + PKCE), then connect to smtp.office365.com:587 via STARTTLS and issue AUTH XOAUTH2 with the token.
• Use the signed-in user’s UPN in the XOAUTH2 string; for shared mailboxes, put the shared mailbox address in the user= field.

App-only (Exception)

1. App registration: add Application permission Office 365 Exchange Online → SMTP.SendAsApp; grant Admin consent.
2. Register service principal in Exchange and scope it to the mailbox:
   • Grant SendAs to send as the mailbox; FullAccess is only needed for IMAP/POP read access.
3. Request tokens for https://outlook.office365.com/.default; use AUTH XOAUTH2 with the mailbox UPN.

Setup Checklists

Email Team

1. Enable Authenticated SMTP on the sender mailbox (per-mailbox control).
2. For App-only requests:
   • Register the Exchange service principal for the app.
   • Grant SendAs on the target mailbox to the service principal (and FullAccess if POP/IMAP is also required).

App / Dev Team

1. Store Tenant ID, Client ID, and secret/cert securely; keep clocks in sync.
2. Delegated: Use MSAL (Auth Code + PKCE) to get SMTP.Send scoped token; implement token refresh.
3. App-only: Use MSAL client credentials to get https://outlook.office365.com/.default token.
4. Connect to smtp.office365.com on 587 with STARTTLS and issue AUTH XOAUTH2.

Configuration Reference

SMTP Settings

• Server: smtp.office365.com
• Port: 587
• TLS: STARTTLS (required)
• Auth: AUTH XOAUTH2 (OAuth2 access token)
• Sender: service/shared mailbox UPN (e.g., app-sender@dartmouth.edu)

Token Requests

• Delegated: scope https://outlook.office.com/SMTP.Send (+ offline_access if needed).
• App-only: scope https://outlook.office365.com/.default with permission SMTP.SendAsApp.

FAQ

Why prefer delegated?

Delegated tokens naturally scope to the signed-in user, avoiding tenant-wide exposure. App-only is powerful but must be tightly scoped.

Our device/library can’t do delegated. What then?

Use app-only, but the Email Team must register the app’s service principal in Exchange and grant mailbox-level rights to limit access.

Why don’t SMTP-sent messages show in Sent Items?

SMTP doesn’t save a copy. If you need Sent Items, consider Microsoft Graph sendMail.

We get 535 5.7.3 Authentication unsuccessful. What should we check?

• Correct scope (SMTP.Send for delegated, .default for app-only) and admin consent granted.
• Exchange service principal registered (app-only) and mailbox rights applied.
• Authenticated SMTP enabled on the sender mailbox.
• Token not expired; TLS and firewall egress OK; retries implemented.

Need Help?

Questions about which flow to use or want the Email Team to scope an app-only sender? Email help@dartmouth.edu.