innoge/laravel-msgraph-mail
Laravel Microsoft Graph Mail
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:
- In the Entra admin center, go to App registrations and create a new registration. Note the Application (client) ID and the Directory (tenant) ID.
- Under Certificates & secrets, create a client secret, or upload a certificate if you'd rather not rotate secrets (see Certificate Authentication).
- Under API permissions, add the Microsoft Graph application permission
Mail.Sendand grant admin consent. If you send large attachments, addMail.ReadWriteas well. - 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
This package helps prevent performance problems with frequent Policy calls withi...
A state machine for Eloquent, built on native PHP enums. No state classes, no mo...
Powerful PHP database abstraction layer (DBAL) with many features for database s...
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v3.0.0 | ^8.3 | ^12.0| | MIT | |
| v2.0.0 | ^8.2 | ^11.0| | MIT | |
| 1.5.0 | ^8.1 | ^9.38| | MIT | |
| 1.4.3 | ^8.1 | ^9.38| | MIT | |
| 1.4.2 | ^8.1 | ^9.38| | MIT | |
| 1.4.1 | ^8.1 | ^9.38| | MIT | |
| 1.4.0 | ^8.1 | ^9.38| | MIT | |
| 1.3.1 | ^8.1 | ^9.38| | MIT | |
| 1.3.0 | ^8.1 | ^9.38| | MIT | |
| 1.2.0 | ^8.1 | ^9.38| | MIT | |
| 1.1.0 | ^8.1 | ^9.38| | MIT | |
| 1.0.5 | ^8.1 | ^9.38| | MIT | |
| 1.0.4 | ^8.1 | ^9.38| | MIT | |
| 1.0.3 | ^8.1 | ^9.38| | MIT | |
| 1.0.2 | ^8.1 | ^9.38| | MIT | |
| 1.0.1 | ^8.1 | ^9.38| | MIT | |
| 1.0.0 | ^8.1 | ^9.38| | MIT |