Skip to main content
mailkube/mailkube-laravel registers a mailkube mail transport, so Mailables, Mail::to(...), queued mail and Mail::fake() all keep working while delivery goes through mailkube. It is a thin adapter over the PHP SDK, which owns the API surface, the errors and the signature verification. Requires PHP 8.3+ and Laravel 12 or 13.

Install

The service provider is discovered automatically. Add the mailer to config/mail.php:
and point MAIL_MAILER at it:
Laravel 11 is not supported. It is past security support, and the advisory covering it has no patched 11.x release, so Composer’s default audit policy declines to install it.

Send

Your Mailables and Mail::to(...) calls keep working as they are:
The transport maps the sender, recipients including blind copies, the subject, both bodies, attachments and your custom headers. Anything Laravel’s mail API can express passes through. The from comes from the message envelope, so set mail.from or the Mailable’s own sender. Tags, topics, templates, scheduling and idempotency keys have no slot in Laravel’s mail API. Reach them through the SDK client the package binds in the container, which already carries your configuration:
The named-argument surface is the PHP SDK’s.
An inline cid: image degrades to an ordinary attachment: the API’s attachment model has no content id for the reference to resolve against.

Configure

Reading order for every setting: the per-mailer array in config/mail.php, then config/mailkube.php, then the SDK’s own environment fallback. An unset setting is omitted rather than passed as null, and the SDK’s resolution still applies. Publish the config file only if you want to edit it in place: php artisan vendor:publish --tag=mailkube-config. Name a channel from config/logging.php in MAILKUBE_LOG_CHANNEL and the SDK writes its request and response metadata through Laravel’s logging stack at debug level. Bodies are never logged, and Authorization and Idempotency-Key are redacted.

Two accounts, two mailers

Give a mailer its own credentials and it gets its own client:

Handle failures

A failed send raises Symfony’s TransportException with the SDK’s own exception as its previous. That is Laravel’s and Symfony’s error type on purpose: failover transports, queued-mail failure handling and Mail::assertNothingSent() all key off it:
The transport is synchronous on purpose, and it never retries. Send through Mail::queue() and let the queue worker own the retry policy.

Receiving webhooks

The webhook route is off by default. A package should not mount an unauthenticated POST route just for being installed. Opt in by naming a path:
Deliveries are verified against the raw request body and dispatched as one Laravel event. An event type this SDK release does not model still reaches your listener with its payload intact:
Listeners run inside the request unless you queue them, and the endpoint answers as soon as they return. Queue anything slow, or delivery latency becomes retries. The route registers in the api middleware group, which has no CSRF verification; a machine-to-machine POST cannot present a token. If you move it into web, add the path to your CSRF exceptions or every delivery is rejected with a 419. Keep body-rewriting middleware off this path: the signature covers the exact bytes that were sent. The package route answers POST only, and mailkube activates an endpoint only after probing it with GET <url>?hub.mode=subscribe&hub.challenge=<token> and reading the token back. Add the probe route yourself:
To use your own receiver path, point a route at the package’s controller instead of setting MAILKUBE_WEBHOOK_PATH:

Next steps

PHP SDK

The client behind the transport: every named argument, scheduled sends, and the exception tree.

Webhooks

The event catalog WebhookReceived can carry, the signing scheme, and delivery retries.