laravel-bangau-mail maintained by openjournalteam
Laravel Bangau Mail
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=no-reply@example.com
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":"user@example.com","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.