alagaccia/mailer-transport

Custom Laravel mail transport that delivers messages through a mailer HTTP API. Registers the mailer automatically with a configurable name: set MAIL_MAILER and you are done.

v1.1.0 2026-08-05 16:07 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.5
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/mail: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• symfony/mailer: ^7.0|^8.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.7.4
• pestphp/pest-plugin-laravel: ^3.0

MIT

• Andrea Lagaccia

• mailer
• api
• laravel
• transport
• alagaccia

Published on Packagist.org on 2026-08-05 16:07 UTC

README

Custom Laravel mail transport that delivers messages through a mailer HTTP API.

The package registers the mailer automatically (service provider auto-discovery + config injection into mail.mailers.{name}), so no manual changes to config/mail.php or AppServiceProvider are needed.

Installation

composer require alagaccia/mailer-transport

Configuration

Set these variables in your .env:

MAIL_MAILER=custom

CUSTOM_MAILER_HOST=https://mailer.example.com/api/send
CUSTOM_MAILER_KEY=your-api-key
# Optional: mailer/transport name (default "custom")
CUSTOM_MAILER_NAME=custom
# Optional: process the message synchronously on the mailer (default false)
CUSTOM_MAILER_SYNC=false

That's it. Every mail sent by Laravel (Mail::send(), Mailables, notifications, …) is delivered as a JSON POST to CUSTOM_MAILER_HOST authenticated with the X-API-KEY header.

Customizing the mailer name

The mailer name defaults to custom. To use a different one, set CUSTOM_MAILER_NAME (and MAIL_MAILER to the same value):

MAIL_MAILER=acme
CUSTOM_MAILER_NAME=acme

Alternatively, publish the config file and edit it:

php artisan vendor:publish --tag=mailer-transport-config

Payload

{
    "to": ["[e-mail]"],
    "subject": "Subject",
    "body": "<p>HTML body (falls back to text body)</p>",
    "sync": false,
    "attachments": [
        { "filename": "file.pdf", "content": "<base64>", "mime": "application/pdf" }
    ]
}

attachments is present only when the message has attachments.

Overriding the defaults

Any key defined under mailers.{name} in your application's config/mail.php takes precedence over the values injected by the package:

'custom' => [
    'transport' => 'custom',
    'host' => env('CUSTOM_MAILER_HOST'),
    'api_key' => env('CUSTOM_MAILER_KEY'),
    'sync' => true,
],

Testing

composer test