> ## 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.

# PHP SDK

> Install wazobiamail/wazobiamail-php with Composer for transactional email, domains, mailboxes, tracking and webhooks.

The official PHP SDK is a Composer library built on Guzzle 7. It supports PHP 8.1+ and works in plain PHP, Symfony, Slim, custom frameworks and legacy applications.

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

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

## At a glance

| | |
| - | - |
| Runtime | PHP 8.1+ |
| Dependencies | Guzzle 7, `ext-json` |
| Package | `wazobiamail/wazobiamail-php` |
| Install | `composer require wazobiamail/wazobiamail-php` |
| Auth | `X-API-Key` |
| Source | [github.com/WazobiaMail/wazobiamail-php](https://github.com/WazobiaMail/wazobiamail-php) |

## Install

```bash theme={null}
composer require wazobiamail/wazobiamail-php
```

## Configure

```php theme={null}
use WazobiaMail\WazobiaMailClient;

$client = new WazobiaMailClient('wzbm_live_...');

// Or read WAZOBIA_API_KEY / WAZOBIAMAIL_API_KEY:
$client = new WazobiaMailClient();

// Custom gateway or timeout:
$client = new WazobiaMailClient([
    'apiKey' => 'wzbm_live_...',
    'baseUrl' => 'https://app.wazobiamail.com/api/v1',
    'timeout' => 30.0,
]);
```

## Send your first email

The SDK accepts the ergonomic flat shape and normalizes it to the API's nested `content` contract:

```php theme={null}
$result = $client->messages()->send([
    'from' => 'Acme <hello@mail.example.com>',
    'to' => 'customer@example.com',
    'subject' => 'Your order shipped',
    'html' => '<p>Your order is on its way.</p>',
    'text' => 'Your order is on its way.',
    'replyTo' => 'support@example.com',
], 'order-1042-shipped'); // optional Idempotency-Key
```

URL attachments stay on the JSON endpoint:

```php theme={null}
$client->messages()->send([
    'to' => 'billing@example.com',
    'subject' => 'Invoice #1042',
    'html' => '<p>Invoice attached.</p>',
    'attachments' => [
        ['url' => 'https://cdn.example.com/1042.pdf', 'filename' => 'invoice-1042.pdf'],
    ],
]);
```

Inline/base64 attachments are automatically uploaded through the multipart endpoint. You can also pass files explicitly:

```php theme={null}
$client->messages()->sendWithAttachments($payload, [
    ['path' => '/tmp/invoice.pdf', 'filename' => 'invoice.pdf', 'contentType' => 'application/pdf'],
]);
```

## What you can do

* `messages()` — send, URL attachments, multipart attachments, spam check.
* `domains()` — list/create/update/delete, DNS records, mail DNS, verify, Cloudflare.
* `mailboxes()` and `mailboxMessages()` — provision inboxes and read enterprise messages.
* `tracking()` and `templates()` — delivery timeline and reusable templates.
* `relays()` / `smtpRelays()` — customer SMTP relay configuration.
* `webhooks()` — HMAC SHA-256 signature verification and event decoding (no network call).

## Webhooks

```php theme={null}
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WAZOBIA_SIGNATURE'] ?? '';
$secret = getenv('WAZOBIA_WEBHOOK_SECRET');

try {
    $event = $client->webhooks()->constructEvent($payload, $signature, $secret);
} catch (\WazobiaMail\Exceptions\WazobiaException $e) {
    http_response_code(400);
    exit('Invalid webhook');
}
```

## Errors

All failures extend `WazobiaMail\Exceptions\WazobiaException`; specific classes include `AuthenticationException`, `ForbiddenException`, `NotFoundException`, `ValidationException`, `RateLimitException` and `ServerException`.

```php theme={null}
try {
    $client->messages()->send($payload);
} catch (\WazobiaMail\Exceptions\ValidationException $e) {
    print_r($e->getErrors());
}
```

## Framework notes

In Symfony, register `WazobiaMailClient` as a service and inject it into controllers or message handlers. For Laravel, use the dedicated `wazobiamail/wazobiamail-laravel` package so the mail driver, facade and service provider are registered automatically.

## Links

* [Packagist](https://packagist.org/packages/wazobiamail/wazobiamail-php)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-php)
* [Full README](https://github.com/WazobiaMail/wazobiamail-php#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.