Laravel

The mailchannels/mailchannels-php package includes a Laravel service provider that registers mailchannels as a Mail driver. Laravel’s Mail facade is built on Symfony Mailer under the hood, and uses the exact same transport as the Symfony integration.

This plugin is optional and lives alongside the rest of the PHP SDK. The plugin itself can only send mail. It doesn’t implement the full API surface (sub-accounts, keys, webhooks, etc.). For those features, use the SDK’s Client directly.

Prerequisites

Before you send your first message, follow the PHP quickstart prerequisite section. This will walk you through creating an account, generating an API key, and adding the required Domain Lockdown and SPF DNS records.

Installation

composer require mailchannels/mailchannels-php

The SDK also needs a PSR-18 HTTP client and PSR-17 factories. Symfony HTTP Client + Nyholm PSR-7 is a good fit here, since Laravel Mail is built on Symfony Mailer (Guzzle works too, but install one or the other, not both):

composer require symfony/http-client nyholm/psr7

Configuring Laravel

Add a mailchannels mailer

Add a mailchannels mailer in config/mail.php:

config/mail.php

return [
    // ...
    'mailers' => [
        // ...
        'mailchannels' => [
            'transport' => 'mailchannels',
        ],
    ],
];

Add your API key

Add it to config/services.php:

config/services.php

return [
    // ...
    'mailchannels' => [
        'api_key'  => env('MAILCHANNELS_API_KEY'),
        'base_url' => env('MAILCHANNELS_API_URL'), // optional; omit for the default
    ],
];

Point Laravel at the new mailer

Set in your environment or .env file:

.env

MAIL_MAILER=mailchannels
MAILCHANNELS_API_KEY=your-api-key

Sending mail

Once configured, send mail through the standard Mail facade. No MailChannels-specific code is required:

use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

Mail::to('recipient@example.com')->send(new WelcomeEmail());

See Laravel’s docs on generating mailables for everything else Email supports (multiple recipients, reply-to, attachments and so on). Anything built with a Laravel Mailable (from, to/cc/bcc, subject, text/html bodies, attachments) can be sent through this transport.

Only one personalization is ever built per message. If you need to send multiple individualized emails in one request, call the SDK’s Client directly instead of going through Mail. See How emails are structured for more information on personalizations.

Control headers

A Laravel Mailable has no equivalent for some MailChannels-specific features. Reach those instead through custom headers prefixed with x-mailchannels-. The x-mailchannels-* headers are stripped before the message is sent, so recipients never see them. Set these (and any other custom headers) from a Mailable’s headers() method:

use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Headers;

class WelcomeEmail extends Mailable
{
    public function headers(): Headers
    {
        return new Headers(
            text: [
                'X-Misc-Header' => 'welcome-2026',
                'x-mailchannels-transactional' => 'true',
            ],
        );
    }
}

If the same custom header is added twice, only the last value is used.

Boolean headers accept only the literal strings "true" / "false"; anything else throws Symfony\Component\Mailer\Exception\TransportException. An empty value is treated as unset (falls back to the default).

Header	Description
`x-mailchannels-send-async`	Queue the message (`true`, the default) instead of sending it synchronously (`false`). Equivalent to calling the SDK’s `queue()` vs. `send()`. Queued sends report delivery status via webhooks rather than in the response.
`x-mailchannels-click-tracking-enable`	Enable click tracking.
`x-mailchannels-click-tracking-domain`	Custom domain for click-tracking links. See Custom tracking.
`x-mailchannels-open-tracking-enable`	Enable open tracking.
`x-mailchannels-open-tracking-domain`	Custom domain for open-tracking links. See Custom tracking.
`x-mailchannels-unsubscribe-domain`	Custom domain for unsubscribe links. See Custom tracking.
`x-mailchannels-transactional`	Whether the mail is transactional or non-transactional (marketing, etc.). Affects List-Unsubscribe handling, see Unsubscribe.
`x-mailchannels-dkim-domain`	Domain to use for DKIM signing.
`x-mailchannels-dkim-selector`	Selector to use for DKIM signing.
`x-mailchannels-dkim-private-key`	Private key to use for DKIM signing.
`x-mailchannels-campaign-id`	Campaign that this message is part of.

Each of these corresponds directly to a field on the send endpoint. See that reference for full semantics.

This transport only supports DKIM via the x-mailchannels-dkim-* headers above.If a DKIM-Signature header is already present on the message, the message is rejected, since the provided signature won’t match the message the API constructs.See DKIM signing and key management for information on how MailChannels handles signing and keys.

Laravel’s own mail queueing (ShouldQueue mailables, Mail::queue()) is unrelated to the x-mailchannels-send-async control header:The former controls when your application hands the message to the transport; the latter controls whether MailChannels processes it synchronously or asynchronously once it arrives.You can use them independently or together.

Error handling

Any SDK exception raised while sending (authentication, validation, rate limiting, server errors) is caught and re-thrown as Symfony\Component\Mailer\Exception\TransportException. Access the original exception via $e->getPrevious() to inspect it:

use Symfony\Component\Mailer\Exception\TransportException;

try {
    Mail::to($recipient)->send(new WelcomeEmail());
} catch (TransportException $e) {
    $previous = $e->getPrevious();
    if ($previous instanceof \MailChannels\Exception\RateLimitException) {
        // handle rate limit
    } elseif ($previous instanceof \MailChannels\Exception\ValidationException) {
        // handle validation error
    } else {
        // handle other transport errors
    }
}

Limitations

One personalization per message. No per-recipient template data or per-recipient header overrides through this transport.
No Mustache templating. This transport has no way to use mailchannels’ mustache template rendering. If you need to do so, use Laravel’s Blade Template Support, or use the SDK’s Client directly; see Templates for how.
DKIM only via the MailChannels API, as described above.

Next steps

Read the webhooks guide to learn how to get real-time notifications about email delivery, bounces, and complaints.
Explore the API reference to see what else you can do with the API.

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Prerequisites

Installation

Configuring Laravel

Sending mail

Control headers

Error handling

Limitations

Next steps

​Prerequisites

​Installation

​Configuring Laravel

​Sending mail

​Control headers

​Error handling

​Limitations

​Next steps

Prerequisites

Installation

Configuring Laravel

Sending mail

Control headers

Error handling

Limitations

Next steps