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
config/mail.php:
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 andMail::to(...) calls keep working as they are:
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:
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 inconfig/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’sTransportException 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:
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: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:
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.