Download the PHP package wapplersystems/microsoft-graph-mailer without Composer

Microsoft Graph Mailer for TYPO3

Sends TYPO3 system emails via the Microsoft Graph API using OAuth 2.0 client credentials. Built on top of wapplersystems/oauth-service for token acquisition, caching, refresh and BE-configurable client setup.

No SMTP. No mailbox password. No interactive user consent needed.

Why

Office 365 / Exchange Online is phasing out Basic Authentication for SMTP AUTH. Modern delivery uses the Microsoft Graph sendMail endpoint with an OAuth2 bearer token. This extension wires that endpoint into TYPO3's existing Symfony Mailer pipeline so any MailerInterface consumer sends through Graph transparently.

Requirements

• TYPO3 v14
• PHP 8.2+
• wapplersystems/oauth-service ≥ release with tx_oauthsvc_client.metadata
• A Microsoft 365 tenant + Entra ID app registration with the Mail.Send Application permission (admin-consent granted)
• A dedicated service mailbox restricted via Application Access Policy

Installation

Configuration

1. Azure / Microsoft Entra ID — App registration

1. https://entra.microsoft.com → Applications → App registrations → New registration
   • Name: TYPO3 Mailer – yourdomain.com
   • Account type: Single tenant
   • Redirect URI: leave empty (app-only flow, no user login)
2. API permissions → Microsoft Graph → Application permissions
   • Add Mail.Send
   • Click Grant admin consent
3. Certificates & secrets → New client secret
   • Copy the Value (only shown once)
4. Note from the Overview page:
   • Directory (tenant) ID
   • Application (client) ID

2. Restrict the app to one mailbox (Exchange Online PowerShell)

Without this step the app could send from any mailbox in the tenant.

3. TYPO3 — OAuth Services backend module

Go to System → OAuth Services → Clients → New:

Save. The token is fetched lazily on the first mail send and cached by oauth-service (TYPO3 oauth_service cache backend) for its expires_in lifetime.

4. Wire the transport

Add to config/system/additional.php (or set via Admin Tools → Settings → Configure Installation-wide Options → MAIL):

That is the only TYPO3-side configuration. No DSN, no SMTP settings, no mailbox password. The transport reads sender_upn and tenant_id from the OAuth client's metadata at send time.

5. (Recommended) Scheduler

oauth-service ships two console commands. For client-credentials only the cache invalidation matters, but the monitor catches misconfigured credentials early:

Testing

A successful send returns silently. On error the transport throws a GraphMailerException with the Microsoft request-id header — quote that in any Microsoft support case.

Failure handling — the spool fallback

To avoid silently dropping emails when Microsoft Graph rejects a request (no OAuth client configured, expired secret, license issue, 401/403/404 from sendMail, …), the transport writes the original message as an .eml file plus a .json payload record to a spool directory and lets the caller proceed. Default location:

Each undelivered message becomes a pair:

• YYYYMMDD-HHMMSS-recipient_at_domain-xxxxxxxx.eml — full RFC 5322 message; openable in any mail client, useful for human inspection or manual resend
• YYYYMMDD-HHMMSS-recipient_at_domain-xxxxxxxx.json — failure metadata (timestamp, reason, recipients, subject) plus the original Microsoft Graph sendMail payload (graph_payload) so an automated retry does not need to re-parse the .eml

Audit

shows everything currently in the spool with the original failure reason and retry count.

Automatic retry (recommended)

typo3 microsoft-graph-mailer:resend-undelivered iterates the spool and re-posts each entry's graph_payload to Microsoft Graph. On success the pair is deleted; on failure the entry stays in the spool with retry_count incremented and last_retry_error recorded.

Options:

• --limit N — process at most N entries per run (default 50)
• --max-age-days D — delete (abandon) entries older than D days; 0 disables
• --dry-run — list what would be retried without contacting Graph
• --dir PATH — override the spool directory

Schedule this command in the TYPO3 Scheduler module as "Microsoft Graph: resend undelivered emails" (registered task) every five minutes. The task exposes a Batch size and Max age (days) field in the BE form.

Configuration

Sender address & defaultMailFromAddress

The transport calls /users/{sender_upn}/sendMail — Graph treats that mailbox as the authenticated sender. The email's From: header is taken from the Symfony Email::getFrom() (typically TYPO3's $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress']) and placed into message.from of the Graph payload.

When defaultMailFromAddress differs from sender_upn, Exchange Online requires the sender_upn mailbox to hold Send As (or Send on Behalf) permission for the defaultMailFromAddress mailbox. Without it, Graph rejects the request:

Fix in Exchange Online PowerShell:

Or in the Microsoft 365 Admin Center: Active users → \<defaultMail- FromAddress> → Mail → Manage mailbox permissions → Send as → add <sender_upn>.

Notes:

• <defaultMailFromAddress> must be a real mailbox or Shared Mailbox. Pure aliases of sender_upn cannot carry their own permissions — convert the alias into a Shared Mailbox, or align defaultMailFromAddress with sender_upn.
• Send on Behalf (Set-Mailbox -GrantSendOnBehalfTo) is a valid alternative but adds a Sender: header, so recipients see "\<sender_upn> on behalf of \<from>" in their mail client. Usually not desired.
• Permission changes propagate in Exchange Online within minutes (up to one hour). Flush the TYPO3 token cache (typo3 cache:flush) before retrying. Until the permission lands, failed sends accumulate in the spool — re-flight them via typo3 microsoft-graph-mailer:resend-undelivered once it works.

Multiple senders

The transport always targets the first active microsoft_graph OAuth client. To send from a different mailbox in the same tenant, change the sender_upn metadata value. To use a different tenant entirely, create a second client row and deactivate the first.

Limitations

• saveToSentItems is hard-set to false — the service mailbox is typically noreply@… and shouldn't accumulate sent mail. If you need Sent-Folder copies, fork the transport.
• Internet message headers are limited by Graph to x--prefixed custom headers. Standard MIME headers (From/To/Subject/…) are mapped to the corresponding Graph message fields automatically.
• Throttling: Microsoft Graph applies a 10,000 messages/24h limit per app per mailbox. For bulk newsletter traffic use a dedicated newsletter service (CleverReach, Mailchimp, …) instead.

License

GPL-2.0-or-later