Laravel MailBridge

Provider-neutral transactional and marketing email for Laravel 12+.

MailBridge keeps your application code stable while providers, SDKs, template ids, and marketing APIs vary behind adapters. Your app uses the same MailBridge methods while SendGrid, Amazon SES, Brevo, MailerSend, Resend, Postmark, Mailchimp, Kit, MailerLite, Mailgun, Mailjet, and AutoSend each run through their official SDKs internally.

Documentation

Full docs: https://ashraful19.github.io/laravel-mailbridge/

Source docs:

• Installation
• Provider install
• Laravel mail compatibility
• Transactional email
• Hosted templates and provider-specific data
• Marketing email
• Response shapes
• Exception handling
• Fallback
• Testing
• Security
• Capabilities
• Troubleshooting

Quick Start

composer require ashraful19/laravel-mailbridge
php artisan vendor:publish --tag=mailbridge-config
php artisan mailbridge:install

mailbridge:install opens a terminal checklist so you can install one or more provider SDKs. The base package does not install every SDK.

Set runtime provider settings in .env:

MAIL_FROM_ADDRESS=hello@example.com
MAIL_FROM_NAME="Example App"
MAILBRIDGE_TRANSACTIONAL=brevo
MAILBRIDGE_MARKETING=mailerlite
BREVO_API_KEY=
SENDGRID_API_KEY=
SENDGRID_MARKETING_SENDER_ID=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
MAILERLITE_API_KEY=
MAILCHIMP_API_KEY=
MAILCHIMP_SERVER_PREFIX=us1
MAILCHIMP_AUDIENCE_ID=
MAILCHIMP_TRANSACTIONAL_API_KEY=
KIT_API_KEY=
MAILJET_API_KEY=
MAILJET_SECRET_KEY=
AUTOSEND_API_KEY=

Optional: set provider-level sender defaults in config/mailbridge.php (for providers that should use a different sender than global MAIL_FROM_*):

'providers' => [
    'postmark' => [
        'server_token' => env('POSTMARK_SERVER_TOKEN'),
        'from' => [
            'address' => env('POSTMARK_FROM_ADDRESS'),
            'name' => env('POSTMARK_FROM_NAME'),
        ],
    ],
],

Sender precedence is: ->from(...) at runtime -> mailbridge.providers.<provider>.from -> mailbridge.from (MAIL_FROM_*).

Configure template and list mappings in config/mailbridge.php (templates, lists).

Basic Usage

Existing Laravel mail stays compatible:

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

Send a Laravel Mailable through MailBridge:

MailBridge::transactional()
    ->to($user->email, $user->name)
    ->send(new WelcomeMail($user));

Send a provider-hosted template:

MailBridge::transactional()
    ->template('welcome')
    ->to($user->email)
    ->data(['name' => $user->name])
    ->send();

Use provider-specific template data when providers expect different variable names:

MailBridge::transactional()
    ->template('welcome')
    ->to($user->email)
    ->data(['name' => $user->name])
    ->dataFor('brevo', ['FIRSTNAME' => $user->name])
    ->dataFor('postmark', ['name' => $user->name])
    ->send();

Send through one provider for this request:

MailBridge::transactional('postmark')
    ->withFallback(false)
    ->to($user->email)
    ->subject('Welcome')
    ->text('Hello')
    ->send();

Subscribe a marketing contact:

use Ashraful19\LaravelMailbridge\Data\Subscriber;

MailBridge::marketing()
    ->list('signup')
    ->subscribe(Subscriber::make($user->email)->name($user->name));

Work with subscribers and campaigns using the same API across marketing providers:

use Ashraful19\LaravelMailbridge\Data\Campaign;

MailBridge::marketing()
    ->list('signup')
    ->unsubscribe($user->email);

$subscriber = MailBridge::marketing()->getSubscriber($user->email);

$campaign = MailBridge::marketing()
    ->createCampaign(
        Campaign::make('Product Launch')
            ->subject('New release is live')
            ->html('<h1>Launch</h1>')
            ->list('signup')
    );

Return Objects

Transactional send returns SendResult:

$result = MailBridge::transactional()
    ->to($user->email)
    ->subject('Welcome')
    ->text('Hello')
    ->send();

$result->provider;  // string, selected provider name
$result->messageId; // ?string, provider message id when available
$result->metadata;  // array, provider-specific extra data

Marketing actions return MarketingResult:

$result = MailBridge::marketing()
    ->list('signup')
    ->subscribe(Subscriber::make($user->email));

$result->provider;  // string
$result->operation; // string, e.g. subscribe, campaign_create
$result->metadata;  // array, provider-specific fields

Subscriber lookup returns SubscriberRecord|null:

$record = MailBridge::marketing()->getSubscriber($user->email);

// null when subscriber not found
$record?->provider; // string
$record?->email;    // string
$record?->data;     // array, provider-native payload

Providers

Provider SDKs are installed only when selected, and each install command uses the exact SDK version tested by MailBridge.

Run health checks anytime:

php artisan mailbridge:doctor

Smoke-test real provider APIs before releasing:

php artisan mailbridge:verify --provider=brevo --email=test@example.com --cleanup

Features

Transactional email:

Provider note: SendGrid, Brevo, and Mailjet marketing list IDs must be numeric. MailBridge validates these IDs before building provider payloads.

Marketing email currently implemented in the common API:

Why MailBridge

Exception Handling

MailBridge throws typed exceptions for common validation and configuration errors. All validation-focused exceptions extend MailbridgeValidationException, so existing broad catches still work.

For full guidance and catch examples, see Exception handling.

License

Laravel MailBridge is open-sourced software licensed under the MIT license.