Office 365 SMTP OAuth2

Send your Drupal site's emails through Microsoft 365 / Office 365 (smtp.office365.com) with OAuth2 (XOAUTH2) instead of a mailbox password. Microsoft is phasing out Basic authentication for SMTP AUTH: this module keeps your site sending with token-based authentication, without any external library.

Features

• Mail plugin for Drupal's mail system: core, contrib and custom emails are delivered by Microsoft 365.
• OAuth2 authorization code flow with the delegated SMTP.Send permission. No password is stored; tokens are refreshed automatically and safely under concurrent requests.
• Secret outside exported configuration: the client secret can be defined in settings.php.
• Verified TLS: certificate and host name checked after STARTTLS, TLS 1.3 supported.
• Standards-compliant messages: plain text and HTML, encoded subjects and sender names, several To/Cc/Bcc recipients, Reply-To.
• Attachments from public://, private:// or temporary://, or generated in memory, with a configurable size limit.
• Status report checks (configuration, authorization, expired or revoked token) and a test form that shows the raw SMTP response.

Requirements

• Drupal 10.3 or later, or Drupal 11; PHP 8.1+ with the OpenSSL extension.
• A Microsoft 365 mailbox with Authenticated SMTP (SMTP AUTH) enabled.
• An app registration in Microsoft Entra ID with a client secret and the delegated Office 365 Exchange Online › SMTP.Send permission, with admin consent.

No other Drupal module or PHP library is required.

Installation

composer require 'drupal/o365_smtp:2.0.x-dev@dev'
drush en o365_smtp

Configuration

1. In Microsoft Entra ID, register an application with the Web redirect URI https://example.com/admin/config/system/o365_smtp/oauth/callback and create a client secret.
2. Add the delegated permissions Office 365 Exchange Online › SMTP.Send and Microsoft Graph › offline_access, then grant admin consent.
3. Enable SMTP AUTH on the sending mailbox (Microsoft 365 admin center › Users › Mail › Manage email apps › Authenticated SMTP).
4. In Drupal, open Configuration › System › Office 365 SMTP Settings (/admin/config/system/o365_smtp), enter the client ID, tenant ID, client secret and From address, save, then click Authorize with Office 365 and sign in with the sending mailbox.
5. Send a message from the Test Email tab, then make the module the default mail system, for example with drush config:set system.mail interface.default o365_smtp_mail or the Mail System module.

On production sites, keep the secret out of config/sync:

$settings['o365_smtp.client_secret'] = getenv('O365_SMTP_CLIENT_SECRET');

The complete setup guide and troubleshooting (common 535 5.7.139 and AADSTS… errors) are in the README.

Upgrading from 10.x-1.x

2.0.x requires Drupal 10.3 and changes the OAuth redirect URI. After updating, run drush updatedb, export the configuration, and replace /phpmailer_oauth2/aad-callback with /admin/config/system/o365_smtp/oauth/callback in Microsoft Entra ID before the next authorization. Sending keeps working in the meantime. All steps are listed in the CHANGELOG.

Support

Report bugs and feature requests in the issue queue. Please include the raw SMTP response displayed by the test form.