README

About the package

Laravel Graph Transport is a Laravel plugin that provides a mail driver for the Laravel framework to send emails using Microsoft Graph.

Features

• ✅ Native Laravel mail driver — use Mail::, Mailables, and queues as you normally would
• ✅ OAuth client credentials — automatic token retrieval and caching via Azure AD
• ✅ HTML & plain text — both content types are supported
• ✅ Attachments & inline images — including cid: images in HTML emails
• ✅ CC, BCC & Reply-To — full recipient support
• ✅ Custom headers — X-* headers are forwarded to Microsoft Graph
• ✅ Large attachments — chunked upload via Microsoft Graph upload sessions (>3.5 MB)

Requirements

• PHP ^8.3,^8.4 or ^8.5
• Laravel ^12.0, or ^13.0

📥 Installation

1. Install the Package via composer

composer require codewow/laravel-graph-transport

2. Configuring the mail driver

To let Laravel know that you want to use the Microsoft Graph driver, you need to add the microsoft_graph mail driver to your config/mail.php file.

'microsoft_graph' => [
    'transport' => 'microsoft_graph',
    'client_id' => env('MICROSOFT_GRAPH_CLIENT_ID'),
    'client_secret' => env('MICROSOFT_GRAPH_CLIENT_SECRET'),
    'tenant_id' => env('MICROSOFT_GRAPH_TENANT_ID'),
    'from' => [
        'address' => env('MAIL_FROM_ADDRESS'),
        'name' => env('MAIL_FROM_NAME'),
    ],
    'save_to_sent_items' => env('MAIL_SAVE_TO_SENT_ITEMS', false),
    'skip_large_attachments' => env('MAIL_SKIP_LARGE_ATTACHMENTS', false),
],

For the client_id, client_secret and tenant_id you need to use the values from the Azure App Registration.

The save_to_sent_items option determines whether a sent email should be saved to the sender's "Sent Items" folder. When set to true, the email is saved automatically. By default this is false.

The skip_large_attachments option determines how attachments larger than 3.5 MB are handled. When set to true, large attachments are skipped and the email is sent without them. When set to false (default), large attachments are uploaded via a Microsoft Graph upload session.

Authentication: This package uses the OAuth client credentials flow. Access tokens are requested and cached automatically — no manual OAuth setup is required in your application.

Application permissions: Configure Application permissions in Azure (not Delegated). The app acts on its own behalf to send mail from a mailbox in your tenant.

from.address is required and must be a valid mailbox in your Azure tenant. Microsoft Graph sends mail via /users/{from}/sendMail, so this address must match a mailbox the app is allowed to use. You can override the sender per Mailable with ->from(), but that address must also be a valid mailbox in your tenant — otherwise Microsoft Graph will return an API error.

3. Switch default mail driver

After you've configured the mail driver, let Laravel know that you want to use the Microsoft Graph driver by setting the environment variable.

MAIL_MAILER=microsoft_graph

4. Send an email

Once configured, send mail as you normally would:

use Illuminate\Support\Facades\Mail;

Mail::to('user@example.com')->send(new WelcomeMail());

⚙️ Creating an Azure App Registration

To communicate with Microsoft Graph, you need to create an Azure App Registration. You need to register an Azure App in your Azure Active Directory tenant. You can do this by following the steps in the Microsoft Graph documentation.

After creating the App you have to add the following Application permissions to the App under the "Microsoft Graph" section:

• Mail.Send — required for sending emails
• Mail.ReadWrite — required for large attachments (>3.5 MB)

Now you have to Grant Admin Consent for the App. You can do this by following the steps in the Microsoft Graph documentation.

🧪 Testing

The package uses Pest for testing. Tests use HTTP fakes and do not require a live Microsoft Graph connection.

composer test

🔄 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security Vulnerabilities

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

👏 Credits

• Jessedev1
• All Contributors

📜 License

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