Laravel Msgraph Mail Laravel Package

Product Decisions This Supports

• Build vs. buy for transactional email. If your product sends low-volume, high-value transactional mail (invites, password resets, approval notifications, receipts, alerts) to users in Microsoft 365 tenants, this package removes the need for a paid ESP (SendGrid/Postmark/Mailgun/SES) and removes the need to hand-roll a Graph transport. The decision it unlocks is "no new email vendor in the stack," which shortens procurement and avoids a new data processor in your DPA/subprocessor list.
• Enterprise-readiness roadmap item. "Sends from our own tenant, appears in the user's Sent Items, obeys our Exchange policies" is a recurring checkbox in enterprise security reviews. Supporting Graph mail as a first-class mailer is a concrete, low-cost way to close it — and it's increasingly required, since Microsoft has retired basic-auth SMTP and many tenants disable SMTP AUTH by default. For those customers, an SMTP-based mailer is not a degraded option, it's a non-option.
• Compliance and data-residency posture. Mail never leaves the customer's Microsoft tenant and is not relayed through a third-party processor. This is directly relevant if you sell into regulated buyers (health, finance, public sector) where "where does the email content transit" is a questionnaire line item. save_to_sent_items additionally supports audit/retention requirements ("all outbound mail must be retained in the mailbox").
• Operational roadmap: credential hygiene. The certificate-auth path (JWT client assertion) means no 12–24 month client-secret rotation runbook. That's a small but real reduction in on-call toil and a specific answer to "how do you handle secret rotation?" in a security review. Worth deciding early — migrating from secret to certificate later is easy at the config level, but the Azure-side upload and the cache:clear step are easy to forget.
• Feature scoping: attachments. Mails over ~3 MB are handled automatically via draft + chunked upload sessions, at the cost of the extra Mail.ReadWrite application permission. This is a genuine product decision: "do we support large attachments, and are we willing to ask the customer's admin for a broader permission scope?" For most products the answer is "no — send a download link," which keeps the permission request minimal and materially eases admin consent.
• Feature scoping: per-mailbox sending. The from address must be a real, licensed mailbox (user or shared) in the tenant, and per-Mailable ->from() overrides retarget the Graph call. That makes "send as a shared mailbox like [email protected]" a shippable capability — but it also means each sending identity is an IT provisioning task, not a config change. Plan the onboarding flow accordingly.
• Use cases this fits: internal tools and back-office apps on Laravel; B2B SaaS where the customer's IT wants mail to originate from their tenant; per-tenant notification systems; anything migrating off deprecated Office 365 SMTP.
• Use cases this does not fit: marketing/bulk campaigns, per-recipient personalized email at volume, or anything with deliverability analytics, bounce/complaint webhooks, or A/B testing requirements.

When to Consider This Package

Adopt when most of these hold:

• The product is Laravel (this is a mail transport registered via package auto-discovery — it's a drop-in MAIL_MAILER switch, not an SDK you code against).
• Mail is transactional and low volume, sent from one or a small number of mailboxes. Microsoft throttles Graph sendMail per-mailbox (on the order of ~30 messages/minute and ~10k recipients/day — verify current published limits before committing to a volume assumption). This is fine for per-user notifications and wrong for fan-out.
• The sending tenant is a single Microsoft 365 tenant you control or can get admin cooperation from — client-credentials flow requires an Entra ID app registration with Mail.Send application permission and admin consent. That is a governance dependency, not a coding task, and it is the single largest schedule risk in adoption. Budget days-to-weeks for a customer's IT to approve, not hours.
• Your team is willing to own a very thin dependency (86 stars, 0 dependents, sole maintainer). Mitigation: the surface is one mail transport; forking or replacing it is a day of work, not a quarter. Treat it as a small, reversible bet rather than infrastructure.
• You're willing to queue mail with retries ($tries, backoff) rather than send synchronously — Graph is transiently slow and will occasionally time out. If your architecture assumes a synchronous send in the request path, fix that first.

Look elsewhere when:

• You need deliverability tooling. No bounce/complaint handling, no suppression lists, no open/click analytics, no reputation management. That's an ESP's job.
• You're a multi-tenant SaaS sending as each customer. Every tenant needs its own app registration + admin consent — an onboarding funnel most customers will stall in. Either send from your own tenant (simpler, but you lose the "from their domain" benefit) or use an ESP with per-domain authentication.
• You can't get Mail.Send application permission with admin consent. If the customer's security team won't grant tenant-wide mail-send to your app, this package cannot work; there is no delegated-user alternative here.
• You're not on Laravel, or you're on a Laravel version where the mail transport internals diverge — the package depends on framework mail plumbing and will lag framework changes.
• You need inbound mail parsing or mailbox automation — this is outbound-only.
• Attachment payloads above Graph's ~150 MB upload-session ceiling are a hard requirement.
• You need guaranteed long-term vendor support / SLA. MIT, single maintainer, no commercial backing. Fine as a component; not fine as a load-bearing platform dependency with contractual support obligations.

Adoption notes worth writing into the ticket: pin to 2.x and read UPGRADE.md — 1.x differs on save_to_sent_items scoping, large-mail handling, and certificate auth. After rotating credentials or granting new Graph permissions, php artisan cache:clear is mandatory because tokens are cached per tenant+client for their lifetime. Custom headers only survive if prefixed X-; recipient display names are dropped by Graph. These are all small but they are the exact things that generate support tickets.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can send our product's transactional email directly through the customer's own Microsoft 365 tenant using Microsoft's supported API, instead of SMTP or a third-party email vendor. That means: no new vendor contract, no per-email fees, no customer data passing through an additional processor, and it satisfies the "must originate from our tenant and be retained in our mailbox" requirement that shows up in most enterprise security reviews. Microsoft has already retired the old SMTP authentication path, so this is increasingly the only compliant option for Microsoft-centric customers. The cost is small — it's a configuration change in a Laravel app, not a new subsystem — and the main effort is a one-time Azure app registration that requires the customer's IT admin to click "approve."

For engineering (the summary): It's a Laravel mail transport, installed via auto-discovery, activated by setting MAIL_MAILER=microsoft-graph plus tenant/client credentials in a config/mail.php mailer block. There is no package-specific API — you keep using Mail::, Mailables, and Notifications exactly as today, which means the integration cost is configuration and credential setup, not code. It uses OAuth2 client credentials with Mail.Send application permission; prefer certificate auth over client secrets so we don't own a rotation runbook. Two things to design for up front: (1) queue all sends with retries and backoff — Graph is occasionally slow and we should never block a user request on it; (2) keep attachments small — anything over ~3 MB triggers chunked upload sessions and requires the broader Mail.ReadWrite permission, which is a harder ask of a customer's admin, so default to sending links. Watch three sharp edges: tokens are cached, so credential rotations and new permission grants don't take effect until php artisan cache:clear; only X--prefixed custom headers reach Graph; and the from address must be the mailbox's primary SMTP address (aliases fail with a 404). Finally, treat the dependency as thin and reversible — MIT, one maintainer, no commercial support — so isolate it behind the mailer config and assume we could fork or replace the transport in a day if we had to.