# Send and receive email with PHP and Laravel

Voozin's API is plain HTTPS and JSON, so any PHP version with cURL works. For WordPress, use the [plugin](https://voozin.com/docs/wordpress).

## Plain PHP

```php
<?php
function voozin_send(array $email, ?string $idempotencyKey = null): array {
    $headers = [
        'Authorization: Bearer ' . getenv('VOOZIN_API_KEY'),
        'Content-Type: application/json',
    ];
    if ($idempotencyKey) $headers[] = 'Idempotency-Key: ' . $idempotencyKey;

    $ch = curl_init('https://api.voozin.com/v1/emails');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($email),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $data = json_decode((string) $body, true);
    if ($status >= 400) throw new RuntimeException($data['message'] ?? "Voozin error $status");
    return $data;
}

voozin_send([
    'from' => 'Acme <orders@acme.com>',
    'to' => ['ada@example.com'],
    'subject' => 'Order #1042 confirmed',
    'html' => '<p>Thanks for your order!</p>',
], 'order-1042-confirmation');
```

## Laravel

Add the key to `.env` and `config/services.php`:

```php
// config/services.php
'voozin' => [
    'key' => env('VOOZIN_API_KEY'),
    'webhook_secret' => env('VOOZIN_WEBHOOK_SECRET'),
],
```

Send with the HTTP client:

```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.voozin.key'))
    ->withHeaders(['Idempotency-Key' => "order-{$order->id}-confirmation"])
    ->retry(3, 500, throw: false)
    ->post('https://api.voozin.com/v1/emails', [
        'from' => 'Acme <orders@acme.com>',
        'to' => [$order->email],
        'subject' => "Order #{$order->id} confirmed",
        'html' => view('emails.order-confirmed', ['order' => $order])->render(),
    ])
    ->throw();
```

To keep using Laravel's `Mail` facade and Mailables, configure the SMTP mailer with a Voozin mailbox and app password (see [SMTP](https://voozin.com/docs/smtp)):

```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.inboxcluster.net
MAIL_PORT=587
MAIL_USERNAME=no-reply@acme.com
MAIL_PASSWORD=your-app-password
MAIL_FROM_ADDRESS=no-reply@acme.com
```

## Receive webhooks in Laravel

```php
// routes/api.php
Route::post('/webhooks/voozin', function (Illuminate\Http\Request $request) {
    $raw = $request->getContent();
    $headers = [
        'webhook-id' => $request->header('webhook-id'),
        'webhook-timestamp' => $request->header('webhook-timestamp'),
        'webhook-signature' => $request->header('webhook-signature'),
    ];
    abort_unless(voozin_verify_webhook(config('services.voozin.webhook_secret'), $headers, $raw), 400);

    $event = json_decode($raw, true);
    if ($event['type'] === 'inbound.received') {
        App\Jobs\HandleInboundEmail::dispatch($event['data']);
    }
    return response()->noContent();
});
```

`voozin_verify_webhook` is the PHP function from [Webhooks](https://voozin.com/docs/webhooks#verify-the-signature). Routes in `routes/api.php` are exempt from CSRF checks.
