Laravel Msgraph Mail Laravel Package

Technical Evaluation

innoge/laravel-msgraph-mail is a narrow, single-purpose mail transport for Laravel that replaces deprecated Office 365 SMTP with Microsoft Graph's sendMail endpoint. Architecturally, it fits cleanly because it plugs into Laravel's existing mail manager via package auto-discovery and registers a microsoft-graph transport — there is no bespoke API for developers to learn. Mailables, Mail:: facades, and Notifications work unchanged, which keeps the blast radius small and makes this a genuine drop-in swap rather than an integration project.

Integration feasibility is high for any Laravel team already on Microsoft 365. All configuration lives in config/mail.php under mailers, so it follows standard Laravel conventions, and the switch is largely an env-var change (MAIL_MAILER=microsoft-graph) plus Azure app registration. That said, the real prerequisite work is organizational rather than technical: an Entra ID app registration with the Graph Mail.Send application permission and admin consent, plus a licensed or shared mailbox whose primary SMTP address serves as the sender. Certificate-based auth (signing a JWT client assertion) is available and preferable for production since it avoids rotating client secrets — but it requires the certificate be uploaded to the app registration and depends on ext-openssl.

Technical risks are moderate and mostly operational. The 3 MB boundary is the sharpest edge: mails exceeding it automatically fall back to draft + chunked attachment upload sessions, which silently requires the broader Mail.ReadWrite permission and will throw MissingMailReadWritePermission otherwise. Token caching (per tenant + client, expires_in minus 60s) means credential rotations and newly granted permissions are not picked up until the cache is cleared — a classic source of "we granted the permission and it still fails" incidents. Custom headers are only forwarded when prefixed X-; recipient display names are dropped; and the from address must be a real primary SMTP mailbox, so shared-mailbox and alias topologies need vetting. The package sits at 86 stars, zero dependents, and a single-maintainer profile — bus factor is a real consideration, though the MIT license and thin surface area limit lock-in.

Key questions for the TPM to resolve before committing: (1) Which sender mailboxes are in scope, and are they primary SMTP addresses or aliases? (2) Does any workflow send attachments that could approach or exceed 3 MB, and if so, will Mail.ReadWrite be approved? (3) Is certificate auth acceptable to the identity team, or must we use client secrets with a rotation runbook? (4) Is there an existing Exchange ApplicationAccessPolicy that would restrict the app to specific mailboxes? (5) Who owns the Azure app registration lifecycle, and what is the fallback if the package is abandoned?

Integration Approach

The stack fit is essentially "any Laravel 9+ application on Microsoft 365." Because the transport is registered through auto-discovery and configured only through config/mail.php, there is no service provider wiring, no publishable config, and no vendor migration to sequence against the framework. This is the ideal shape for a TPM to schedule: the code change is trivial and reversible; the dependencies are all external.

Migration path from deprecated Office 365 SMTP is a clean cutover per environment. The practical sequencing is: (1) create the Entra ID app registration and upload the certificate (or secret) with Mail.Send application permission plus admin consent — allow lead time for identity-team review; (2) confirm the sender mailbox exists and note its primary SMTP address; (3) add the microsoft-graph mailer block to config/mail.php and populate MICROSOFT_GRAPH_* env vars; (4) flip MAIL_MAILER in a non-production environment and send a smoke-test mailable; (5) run php artisan config:clear (and cache:clear if tokens may be cached) after any credential or permission change; (6) promote through staging to production. If attachments over 3 MB are in scope, add the Mail.ReadWrite grant as a separate, earlier line item so it lands before cutover rather than as an incident.

Compatibility notes worth flagging in the plan: the documentation is explicitly for package 2.x, and 1.x differs materially (save_to_sent_items only honored on a mailer literally keyed microsoft-graph, no certificate auth, ~4 MB cap with no upload sessions). Teams inheriting an older install should read UPGRADE.md and treat 1.x → 2.x as its own scoped task. Because the mailer block works under any key in 2.x, you can define a second mailer entry for a different sender mailbox — useful for multi-brand or per-tenant sending without code changes. A low-risk rollout pattern is to keep the SMTP mailer configured alongside the Graph mailer and switch via env, giving a one-variable rollback.

Operational Impact

Maintenance burden is low but not zero, and it is concentrated in the identity layer. Certificate expiry, secret rotation, and permission changes all require a php artisan cache:clear afterward — this should be written into the rotation runbook, not discovered during an outage. Upgrades are simple (no published config to merge), but the package's small maintainer base and zero dependent projects mean the team should be prepared to fork or vendor it; the thin, standards-based surface makes that a days-not-months proposition.

Support and failure modes are well-charted, which is a genuine operational asset: the skill documentation includes a symptom-to-cause table covering the full spectrum — AADSTS7000215 (wrong/expired secret or the secret ID copied instead of its value), AADSTS700016/AADSTS90002 (wrong client or tenant ID), AADSTS700027 (certificate not uploaded or mismatched), 403 ErrorAccessDenied (missing Mail.Send, no admin consent, or an Exchange ApplicationAccessPolicy), 404 ErrorInvalidUser (from address is not a real primary SMTP mailbox), and ErrorMessageSizeExceeded (past Graph's 150 MB session ceiling — switch to download links). First-line responders can triage from that table without engineering escalation.

Scaling characteristics are favorable for typical transactional volumes: Graph is a managed service, the transport is stateless, and token caching avoids per-message auth overhead. The genuinely important operational guidance is to queue mail with retries and backoff rather than sending synchronously in request cycles — Graph is documented as transiently slow or unreachable, so cURL error 28 timeouts should be absorbed by the queue, not by raising timeouts. Note that retries interact with save_to_sent_items: when enabled, a retried send can produce duplicate Sent Items entries, and when disabled the sent copy is deleted after the fact with cleanup on failure — teams should decide this policy deliberately rather than inherit the false default.

Ramp-up for the team is short. Developers need no new API knowledge — Mailables and Notifications are unchanged — so the learning curve is almost entirely on whoever owns the Azure app registration and the sender-mailbox inventory. Budget roughly a half-day of engineering plus however long the identity team's consent and access-policy review takes, and document three things up front: the sender mailbox (primary SMTP) per environment, the auth method and rotation cadence, and the queue-with-retries configuration for any mailer using this transport.