New

Just launched: Vueblocks, a brand-new search engine for Vue packages! Explore Vueblocks →

innoge/laravel-msgraph-mail

Laravel Mail driver for Microsoft Office 365 using the MSGraph API
807,757 88
Install
composer require innoge/laravel-msgraph-mail
Latest Version:v3.0.0
PHP:^8.3
Laravel:12 · 13
Older releases:9 · 10 · 11
License:MIT
Last Updated:Nov 2, 2026
Links: GitHub  ·  Packagist
Maintainer: geisi

Laravel MsGraph Mail

Laravel Microsoft Graph Mail

Latest Version on Packagist Laravel Version GitHub Tests Action Status Total Downloads

Introduction

Microsoft 365 is retiring basic authentication for SMTP, and sending through a shared Exchange mailbox with a password was never a great idea anyway. Laravel Microsoft Graph Mail gives Laravel a microsoft-graph mail transport that sends your mail through the Microsoft Graph API instead, authenticated as an Entra app with a client secret or a certificate.

Your mailables, notifications and Mail::to(...) calls stay exactly as they are. You only switch the mailer:

MAIL_MAILER=microsoft-graph

Large attachments are sent through Microsoft Graph upload sessions automatically, so a 20 MB PDF works just like a two-line password reset.

Installation

The package requires PHP 8.3+ and Laravel 12 or 13. Install it with Composer:

composer require innoge/laravel-msgraph-mail

Registering the Entra App

The transport authenticates as a Microsoft Entra app with an application permission:

  1. In the Entra admin center, go to App registrations and create a new registration. Note the Application (client) ID and the Directory (tenant) ID.
  2. Under Certificates & secrets, create a client secret, or upload a certificate if you'd rather not rotate secrets (see Certificate Authentication).
  3. Under API permissions, add the Microsoft Graph application permission Mail.Send and grant admin consent. If you send large attachments, add Mail.ReadWrite as well.
  4. Limit the app to the mailboxes it may send from. An application permission covers every mailbox in your tenant by default, so restrict it with RBAC for Applications or an Application Access Policy.

Prefer a walkthrough with screenshots? There's a blog post covering every step.

Configuring the Mailer

Add a microsoft-graph mailer to the mailers array of your config/mail.php configuration file:

'microsoft-graph' => [

    /*
     * The transport registered by this package. Do not change it.
     */
    'transport' => 'microsoft-graph',

    /*
     * The Directory (tenant) ID and the Application (client) ID of your Entra app registration.
     */
    'tenant_id' => env('MICROSOFT_GRAPH_TENANT_ID'),
    'client_id' => env('MICROSOFT_GRAPH_CLIENT_ID'),

    /*
     * A client secret of the app registration. Leave it out when you authenticate with a certificate
     * instead, which takes precedence once it is filled.
     */
    'client_secret' => env('MICROSOFT_GRAPH_CLIENT_SECRET'),

    /*
     * Optional. The sender of every mail sent through this mailer. Omit the whole key to use the global
     * mail.from configuration. The address must be the primary SMTP address of a real mailbox in your tenant.
     */
    'from' => [
        'address' => env('MAIL_FROM_ADDRESS'),
        'name' => env('MAIL_FROM_NAME'),
    ],

    /*
     * Optional. Whether sent mail is kept in the sender's "Sent Items" folder. Defaults to false;
     * single mailables may override it.
     */
    'save_to_sent_items' => env('MAIL_SAVE_TO_SENT_ITEMS', false),
],

Then add your credentials to the .env file and switch the default mailer:

MAIL_MAILER=microsoft-graph

MICROSOFT_GRAPH_TENANT_ID=
MICROSOFT_GRAPH_CLIENT_ID=
MICROSOFT_GRAPH_CLIENT_SECRET=

Certificate Authentication

Client secrets expire, and an expired secret means mail silently stops going out. Certificates are the more robust choice. Upload the certificate to your app registration under Certificates & secrets, then add a client_certificate entry to the mailer:

'microsoft-graph' => [
    'transport' => 'microsoft-graph',
    'tenant_id' => env('MICROSOFT_GRAPH_TENANT_ID'),
    'client_id' => env('MICROSOFT_GRAPH_CLIENT_ID'),

    /*
     * The certificate uploaded to the app registration and its private key, each as PEM content or a
     * local file path. The passphrase is only needed for an encrypted private key.
     */
    'client_certificate' => [
        'certificate' => env('MICROSOFT_GRAPH_CERTIFICATE'),
        'private_key' => env('MICROSOFT_GRAPH_PRIVATE_KEY'),
        'passphrase' => env('MICROSOFT_GRAPH_KEY_PASSPHRASE'),
    ],
],

Certificate authentication requires the openssl PHP extension. The certificate and key are read when the mailer is created, so a broken key fails right away with an InvalidCredentialsException rather than on the first send. File paths must point to local files, and no exception message ever contains your key.

Sending Mail

There's nothing new to learn. Once the mailer is configured, send mail the way you always do:

Mail::to($user)->send(new OrderShipped($order));

If microsoft-graph isn't your default mailer, pick it explicitly:

Mail::mailer('microsoft-graph')->to($user)->send(new OrderShipped($order));

Saving Mail to Sent Items

By default, sent mail isn't kept in the sender's "Sent Items" folder. You may change the default with the save_to_sent_items option, or decide per mailable through a Symfony metadata header:

use Symfony\Component\Mailer\Header\MetadataHeader;
use Symfony\Component\Mime\Email;

$mailable->withSymfonyMessage(function (Email $message) {
    $message->getHeaders()->add(new MetadataHeader('save-to-sent-items', 'true'));
});

Large Attachments

Microsoft Graph rejects sendMail requests larger than about 4 MB. When your mail is bigger, the package creates a draft, uploads the attachments in chunks through upload sessions and then sends the draft. You don't have to do anything, but this path needs the Mail.ReadWrite application permission. Without it, the package throws a MissingMailReadWritePermissionException that tells you exactly that.

Microsoft always keeps a sent draft in "Sent Items". When save_to_sent_items is disabled, the package removes it again afterwards, and a failed send cleans up its draft.

Using the Graph Client

The authenticated client behind the transport is available for your own Microsoft Graph calls. It caches its access token, URL-encodes path segments, and only ever sends the token to the Microsoft Graph API:

use InnoGE\LaravelMsGraphMail\Graph\ClientSecret;
use InnoGE\LaravelMsGraphMail\Graph\GraphClient;
use InnoGE\LaravelMsGraphMail\Graph\GraphCredentials;

$graph = new GraphClient(new GraphCredentials(
    tenantId: config('services.graph.tenant_id'),
    clientId: config('services.graph.client_id'),
    authentication: new ClientSecret(config('services.graph.client_secret')),
));

$messages = $graph->request()
    ->get($graph->path('users', 'support@example.com', 'messages'))
    ->throw()
    ->json('value');

innoge/laravel-msgraph-mailbox is built on this client. If you'd like to receive mail as well, it turns Microsoft 365 mailboxes into Laravel events.

AI Agent Support

The package ships a Laravel Boost skill covering configuration, troubleshooting and the Entra app registration. Boost installs it through php artisan boost:install or php artisan boost:update --discover.

Upgrading

Upgrading from 1.x or 2.x? The upgrade guide walks you through every change.

Testing

composer test

Changelog

Please see the CHANGELOG for what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see the License File for more information.

Related Packages

innoge/laravel-policy-soft-cache

This package helps prevent performance problems with frequent Policy calls withi...

83,653 24
innoge/filament-form-faker

A package to generate fake input data for Filament forms.

2,566 16
innoge/laravel-enum-states

A state machine for Eloquent, built on native PHP enums. No state classes, no mo...

8,246 5
doctrine/dbal

Powerful PHP database abstraction layer (DBAL) with many features for database s...

660,512,042 9,702
laravel/framework

The Laravel Framework.

617,629,957 34,997

Version History

Version Released PHP Laravel License
v3.0.0 ^8.3 ^12.0|^13.0 MIT
v2.0.0 ^8.2 ^11.0|^12.0|^13.0 MIT
1.5.0 ^8.1 ^9.38|^10.0|^11.0|^12.0|^13.0 MIT
1.4.3 ^8.1 ^9.38|^10.0|^11.0|^12.0 MIT
1.4.2 ^8.1 ^9.38|^10.0|^11.0|^12.0 MIT