Outlook / Microsoft 365 (OAuth)

The Outlook integration sends Frontmail templates from your Outlook.com, Hotmail or Microsoft 365 (Exchange Online) mailbox through Microsoft Graph. Messages land in your Sent Items, replies come back to your inbox.

Choose Outlook / Microsoft 365 when your company already runs on Microsoft 365 and you want website forms and notifications to come from a real company mailbox (office@example.com) without setting up another provider. Like Gmail, it is meant for low volume – Exchange Online throttles per-mailbox sending and there are no delivery webhooks. For transactional volume use Mailgun, Postmark, Amazon SES or Resend. See the services overview.

SMTP AUTH vs Microsoft Graph

Microsoft 365 also offers SMTP submission (smtp.office365.com:587), and Frontmail’s SMTP service has a preset for it. However, SMTP AUTH is disabled by default in many tenants and Microsoft is retiring Basic authentication (username + password) for SMTP AUTH in Exchange Online. This integration therefore uses OAuth and the Graph sendMail API instead – no password, no SMTP AUTH exception needed, and it works with MFA and Conditional Access.

Prerequisites

An Outlook.com / Hotmail account, or a Microsoft 365 work account with an Exchange Online mailbox (a licence that includes Exchange).
For Microsoft 365: permission to consent to apps. Many organisations allow users to consent to low-risk permissions themselves; others require admin consent – see below.
Nothing else – no Azure app registration of your own.

Connect in Frontmail

Open Email services → Add service → Outlook / Microsoft 365.
Click Connect Outlook / Microsoft 365 and sign in with the mailbox you want to send from.
Review the consent screen. Frontmail requests these delegated permissions:
- Mail.Send – send mail as you. It cannot read, move or delete any email.
- offline_access – keep the permission without you being signed in (this is what gives Frontmail a refresh token).
- openid email – your address, shown on the service page and used as the default From.
Click Accept. You’re redirected back and the service is saved with the connected address.
Optionally adjust Max emails per second (default 0.5/s = 30 per minute) and click Test connection, which refreshes the token.

What is stored: the OAuth refresh token (plus a short-lived access token), encrypted with AWS KMS envelope encryption. Access tokens last about an hour; Microsoft rotates the refresh token on every refresh and Frontmail stores the new one automatically.

If your tenant does not allow user consent, the sign-in stops with “Need admin approval” (or error AADSTS65001 / AADSTS90094). A Global Administrator, Cloud Application Administrator or Application Administrator can then:

approve the pending request in Microsoft Entra admin center → Enterprise applications → Admin consent requests, or
sign in through Connect Outlook / Microsoft 365 themselves and tick Consent on behalf of your organization.

Admins can later restrict the app to specific users under Enterprise applications → Frontmail → Properties → Assignment required.

When the token stops working

The refresh token becomes invalid when:

the user changes or resets their password, or an admin revokes sessions (AADSTS50173),
it is not used for 90 days (AADSTS700082),
a user or admin removes Frontmail from My Apps / Enterprise applications,
a Conditional Access policy starts blocking the app, or the account is disabled.

Frontmail sees invalid_grant and treats it as an auth error: the service is marked unhealthy, you get an email and a dashboard banner, and messages are held (or sent via the fallback service) until you click Reconnect on the service page. Held messages are sent automatically afterwards.

DNS: SPF, DKIM and DMARC

Outlook.com / Hotmail addresses: nothing to do.
Microsoft 365 on your own domain – usually set up during tenant onboarding; check that these exist:

; SPF
example.com.                      TXT    "v=spf1 include:spf.protection.outlook.com -all"

; DKIM – two CNAMEs, then enable DKIM signing in the Microsoft Defender portal
selector1._domainkey.example.com. CNAME  selector1-example-com._domainkey.contoso.onmicrosoft.com.
selector2._domainkey.example.com. CNAME  selector2-example-com._domainkey.contoso.onmicrosoft.com.

; DMARC
_dmarc.example.com.               TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Copy the exact DKIM targets from Microsoft Defender → Email & collaboration → Policies → Email authentication settings → DKIM; newer tenants may show a different target format.
Start DMARC with p=none, tighten later.

From address: Graph sends as the signed-in mailbox. Sending as a shared mailbox or another user requires Send As rights and is currently not supported – such attempts fail with ErrorSendAsDenied.

Regions

No region to choose – Frontmail uses the global Microsoft Graph endpoint (graph.microsoft.com) and the common sign-in endpoint, which works for both personal and work accounts. National clouds (e.g. Microsoft 365 operated by 21Vianet, US Government) are not supported.

Sending limits

Account	Approximate limit
Microsoft 365 / Exchange Online	10,000 recipients per day, 30 messages per minute, 500 recipients per message
Outlook.com / Hotmail	~300 messages per day, 100 recipients per message (lower for new accounts)
Graph `sendMail` (MIME)	up to 4 MB per message including attachments

Frontmail’s default of 0.5 messages per second matches the 30 messages/minute Exchange limit. Exceeding limits returns throttling errors that Frontmail retries with backoff.

Delivery tracking (webhooks)

Microsoft Graph offers no delivery webhooks for sent mail, so nothing needs to be configured and the service page has no webhook URL. Frontmail knows only whether Graph accepted the message (sent) or refused it (failed). Non-delivery reports (NDRs) arrive in your inbox as normal emails and are not added to the Frontmail suppression list. Opens and clicks are not tracked.

Common errors

auth – the service is broken (token revoked or expired, consent missing, no mailbox, send-as denied, 401/403). The service is marked unhealthy; the owner gets an email and a dashboard banner. A fallback service on the template takes over; otherwise the credit is refunded and the message waits in the hold queue as held_service_error, sent automatically after you reconnect (re-checked on save and by the daily health check).
permanent – this message can’t be sent (invalid recipients, too large, invalid request). Fallback service if configured, otherwise failed and refunded.
transient – throttling, 5xx, timeouts. Retried with exponential backoff; after the last attempt failed and refunded.

Microsoft response	Class	What to do
`invalid_grant` – `AADSTS50173` / `AADSTS700082` (grant expired or revoked)	auth	Click Reconnect on the service page.
`AADSTS65001` / “Need admin approval”	auth	Ask a tenant admin to grant consent (see above), then reconnect.
`401 InvalidAuthenticationToken`	auth	Normally fixed by the automatic refresh; if it persists, reconnect.
`403 ErrorAccessDenied` / `Authorization_RequestDenied`	auth	Consent was withdrawn or Conditional Access blocks the app – check with your admin.
`MailboxNotEnabledForRESTAPI`	auth	The account has no Exchange Online mailbox (no licence or on-premises mailbox).
`ErrorSendAsDenied`	auth	Use the connected mailbox address as the From address.
`ErrorQuotaExceeded`	auth	The mailbox is full – free up space so Sent Items can store the message.
`400 ErrorInvalidRecipients`	permanent	See invalid recipient.
`413` / `ErrorMessageSizeExceeded`	permanent	Keep the message with attachments under 4 MB.
`429 ApplicationThrottled` / `ErrorExceededMessageLimit` / `MailboxConcurrency`	transient	Per-mailbox limits hit – Frontmail backs off; lower the volume or use a transactional provider.
`500` / `503 ServiceUnavailable`	transient	Microsoft outage – Frontmail retries.

Checklist

Mailbox with Exchange Online (or Outlook.com) connected via Connect Outlook / Microsoft 365
Consent granted – by the user or, if required, by a tenant admin
Microsoft 365 on own domain: SPF include:spf.protection.outlook.com, DKIM selector1/selector2 enabled, DMARC
Template From = the connected mailbox address
Test connection passes
Volume within 30 messages/minute and the daily recipient limit
Fallback service configured for important templates