openjournalteam/laravel-bangau-mail

Laravel 10 mail transport for an external HTTP delivery API.

0.2.0 2026-07-23 00:46 UTC

Requires

• php: ^8.1
• illuminate/mail: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0 || ^13.0
• symfony/mailer: ^6.0 || ^7.0 || ^8.0
• symfony/mime: ^6.0 || ^7.0 || ^8.0

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• phpunit/phpunit: ^10.0 || ^11.0

MIT

Published on Packagist.org on 2026-07-23 00:47 UTC

README

Bangau is a Laravel 10 mail transport that sends Laravel mail through an external HTTP API. It uses Laravel's normal Mail and queued mail flow, and can fall back to a named SMTP mailer if the API cannot accept a message.

Install

composer require openjournalteam/laravel-bangau-mail
php artisan vendor:publish --tag=bangau-config

Add the API secrets to .env:

BANGAU_ENDPOINT=https://mail-api.example.com
BANGAU_API_KEY=replace-with-a-secret
BANGAU_SENDER=[e-mail]
BANGAU_FALLBACK_MAILER=smtp

Then add a mailer in config/mail.php and make it the default when appropriate:

'default' => env('MAIL_MAILER', 'bangau'),

'mailers' => [
    'bangau' => [
        'transport' => 'bangau',
        'endpoint' => env('BANGAU_ENDPOINT'),
        'api_key' => env('BANGAU_API_KEY'),
        'sender' => env('BANGAU_SENDER'),
        'fallback_mailer' => env('BANGAU_FALLBACK_MAILER', 'smtp'),
    ],
],

The API receives from, to, cc, bcc, subject, text, html, attachments, and meta. Attachments are base64 encoded. A response is considered accepted only on HTTP 202; Bangau uses the first results[*].message_id as Laravel's transport-level message ID.

Set BANGAU_FALLBACK_ON_FAILURE=false or fallback_mailer to null if an API failure must fail the Laravel mail job instead of using SMTP.

API contract

POST {BANGAU_ENDPOINT}/sendmail with headers Accept: application/json, Content-Type: application/json, and X-API-Key. The response must return HTTP 202; a compatible response can include:

{"results":[{"email":"[e-mail]","status":"queued","message_id":"provider-id"}]}

Use HTTPS and keep the API key in environment variables or a secret manager. Do not commit it to package configuration.

Bangau rejects non-HTTPS endpoints by default. Only for a trusted local/internal development endpoint, set BANGAU_ALLOW_INSECURE_ENDPOINT=true explicitly.