> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazobiamail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Package

> Install wazobiamail/wazobiamail-laravel to send Laravel Mail, Mailables and notifications through WazobiaMail.

`wazobiamail/wazobiamail-laravel` plugs WazobiaMail into Laravel's native mail system. Set `MAIL_MAILER=wazobiamail` and existing `Mail`, `Mailables` and notifications keep working while delivery moves to the WazobiaMail API.

> [card] [Packagist](https://packagist.org/packages/wazobiamail/wazobiamail-laravel)
>
> `wazobiamail/wazobiamail-laravel` — v0.1.2

> [card] [Source](https://github.com/WazobiaMail/wazobiamail-laravel)
>
> WazobiaMail/wazobiamail-laravel

## At a glance

| | |
| - | - |
| Runtime | Laravel 10, 11, 12 or 13 |
| PHP | 8.1+ |
| Package | `wazobiamail/wazobiamail-laravel` |
| Install | `composer require wazobiamail/wazobiamail-laravel` |
| Auto-discovery | Service provider + `WazobiaMail` facade |
| Source | [github.com/WazobiaMail/wazobiamail-laravel](https://github.com/WazobiaMail/wazobiamail-laravel) |

## Install

```bash theme={null}
composer require wazobiamail/wazobiamail-laravel
php artisan vendor:publish --tag=wazobiamail-config
```

The package uses Laravel package auto-discovery, so the provider and facade register without editing `config/app.php`.

## Configure

```env theme={null}
MAIL_MAILER=wazobiamail
WAZOBIA_API_KEY=wzbm_live_...
```

Register the mailer in `config/mail.php` if your app does not merge it automatically:

```php theme={null}
'mailers' => [
    'wazobiamail' => [
        'transport' => 'wazobiamail',
    ],
],
```

The published `config/wazobiamail.php` reads `WAZOBIA_API_KEY`, `WAZOBIA_BASE_URL` and `WAZOBIA_TIMEOUT`.

## Send with Laravel Mail

```php theme={null}
use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

Mail::to('customer@example.com')->send(new WelcomeEmail());
```

Mailables and notifications route through the custom transport, so attachments, CC/BCC, reply-to and HTML/text bodies keep their normal Laravel semantics.

## Use the facade

```php theme={null}
use WazobiaMail\Laravel\Facades\WazobiaMail;

$domains = WazobiaMail::domains()->list();
WazobiaMail::messages()->send([
    'from' => 'Acme <hello@mail.example.com>',
    'to' => 'customer@example.com',
    'subject' => 'Hello from Laravel',
    'html' => '<p>Sent through the API.</p>',
]);
```

## Webhook controller

```php theme={null}
use Illuminate\Http\Request;
use WazobiaMail\Laravel\Facades\WazobiaMail;

public function __invoke(Request $request)
{
    $event = WazobiaMail::webhooks()->constructEvent(
        $request->getContent(),
        $request->header('X-Wazobia-Signature', ''),
        config('services.wazobia.webhook_secret'),
    );

    return response()->json(['received' => true]);
}
```

Exclude the webhook route from CSRF in `bootstrap/app.php` or `VerifyCsrfToken`, and always use the raw body for signature verification.

## Errors

The transport surfaces the PHP SDK exceptions (`ValidationException`, `RateLimitException`, `ForbiddenException`, etc.). Let them bubble to Laravel's handler for retries/queue failures, or catch them in the Mailable/job when you need custom behavior.

## Queues

Sending through a queued Mailable/job is recommended for request-path latency. Configure a queue driver and use `Mail::to(...)->queue(...)`. If you need strict duplicate protection across retries, send through the PHP SDK `messages()->send($payload, $idempotencyKey)` instead of the generic Laravel transport.

## Links

* [Packagist](https://packagist.org/packages/wazobiamail/wazobiamail-laravel)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-laravel)
* [Full README](https://github.com/WazobiaMail/wazobiamail-laravel#readme)
* [All official SDKs](https://docs.wazobiamail.com/docs/guides/sdks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.