---
title: SDK PHP
description: "Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en PHP avec billionsend-php : toute l'API, nouvelles tentatives, idempotence."
ai:
  exclude: true
---

Le package `billionsend/billionsend-php` est le client BillionSend pour PHP. Il couvre toutes les opérations de la [référence de l'API](/docs/fr/api-reference) : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs fils de discussion et leurs brouillons, événements de boîte de réception en direct et inscription des agents. Le code source est sur GitHub : [billionsend/billionsend-php](https://github.com/billionsend/billionsend-php).

## Installer

Nécessite PHP 8.1 ou plus récent avec les extensions `curl` et `json`, et rien d'autre.

```sh
composer require billionsend/billionsend-php
```

## Envoyer un e-mail

```php
use BillionSend\Client;

$client = new Client(); // reads BILLIONSEND_API_KEY

$sent = $client->emails->send([
    'from' => 'Acme <hello@acme.dev>',
    'to' => ['success@simulator.amazonses.com'],
    'subject' => 'Welcome to Acme',
    'html' => '<p>Glad you are here.</p>',
], ['idempotency_key' => 'welcome/ana']);

echo $sent['id'];
```

`new Client('bs_...')` prend la clé directement. Le deuxième argument règle le reste : `'base_url'`, `'timeout'` (en secondes par tentative, 60 par défaut), `'max_retries'`, `'headers'` et `'transport'` (tout `BillionSend\Transport`, pour envoyer par votre propre pile HTTP). `BILLIONSEND_BASE_URL` remplace l'URL de l'API.

## Noms des méthodes

Chaque opération est une méthode qui porte le nom de son identifiant dans la [référence de l'API](/docs/fr/api-reference), le chemin séparé par des points devenant une chaîne de services : `emails.send` devient `$client->emails->send()`, `emails.receiving.attachments.list` devient `$client->emails->receiving->attachments->list()`. `emails.metrics` devient `$client->emails->metrics->get()`, à côté de `->links()`, `->countries()` et `->clients()`.

Une méthode prend, dans l'ordre, les paramètres de chemin, le corps de la requête, les paramètres de requête et d'en-tête, puis les options de l'appel. Les corps et les réponses sont des tableaux associatifs avec les noms de champ de l'API elle-même : la référence de l'API les décrit donc champ par champ.

## Idempotence et nouvelles tentatives

Les huit opérations d'envoi (`emails->send`, `emails->batch`, réponses et transferts d'e-mails reçus, `inboxes->send`, `inboxes->drafts->send`, réponses et transferts dans un fil) envoient toujours un `Idempotency-Key`. Sans `'idempotency_key'`, chaque appel en génère une que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n'envoie donc jamais deux fois. Votre propre clé rend aussi sûre une répétition venue d'un autre processus.

Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le `409 concurrent_idempotent_requests` renvoyé tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : `GET`, `PUT`, `DELETE` et les opérations d'envoi. Le client attend ce que demande `Retry-After`, jusqu'à une minute, et sinon espace les tentatives de façon exponentielle, de 0,5 s à 8 s. Le dernier argument de chaque méthode accepte `'idempotency_key'`, `'headers'`, `'timeout'`, `'max_retries'` et `'response_headers' => &$headers` pour cet appel.

## Erreurs

Un appel qui échoue lève `ValidationError` (400, 422), `AuthenticationError` (401, ou aucune clé configurée), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, avec `getRetryAfter()` en secondes), `APIError` (5xx), `APIConnectionError` (aucune réponse) ou `APITimeoutError` (la tentative a dépassé son délai). Toutes se trouvent dans `BillionSend\Exception` et étendent `BillionSendError`, avec `getStatusCode()`, `getErrorName()` (le nom de l'erreur dans l'API), `getMessage()` et `getRequestId()`, le `x-request-id` de la réponse, qui est l'identifiant de la requête dans la page Journaux du tableau de bord.

```php
use BillionSend\Exception\BillionSendError;
use BillionSend\Exception\NotFoundError;

try {
    $email = $client->emails->get($id);
} catch (NotFoundError) {
    // no such email
} catch (BillionSendError $e) {
    error_log(sprintf('%s %s: %s (request %s)', $e->getStatusCode(), $e->getErrorName(), $e->getMessage(), $e->getRequestId()));
}
```

## Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi d'un générateur `...All()` qui va chercher les pages suivantes au fur et à mesure, en remontant lorsque `'before'` est défini :

```php
foreach ($client->contacts->listAll(['limit' => 100]) as $contact) {
    echo $contact['email'], "\n";
}
```

## La boîte de réception d'un agent

Attendez les nouveaux e-mails sur le [flux d'événements](/docs/fr/inboxes) et répondez dans leur fil :

```php
use BillionSend\StreamGapEvent;

$stream = $client->inboxes->events->streamInbox('support@acme.dev', ['types' => 'inbox.email.received']);

foreach ($stream as $event) {
    if ($event instanceof StreamGapEvent) {
        continue; // events may be missing: read the threads again
    }
    $data = $event->payload();
    $client->inboxes->threads->emails->reply(
        $event->inboxId(),
        $data['thread_id'],
        $data['email_id'],
        ['text' => 'Thanks, we are on it.'],
        ['idempotency_key' => "reply/{$data['email_id']}"],
    );
}
```

Le flux se reconnecte avec `Last-Event-ID` lorsque la connexion tombe et rejoue ce qu'il a manqué. Gardez `$stream->lastEventId()` et repassez-le dans l'option `'last_event_id'` pour reprendre après un redémarrage. Un `StreamGapEvent` arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. Les options `'max_reconnects'` (5 par défaut), `'reconnect_delay'` et `'reconnect' => false` règlent la reconnexion. Le flux d'une boîte de réception se termine une fois cette boîte supprimée ou expirée ; `$client->inboxes->events->stream()` suit toutes les boîtes que la clé peut lire.

## Vérifier les webhooks

`Webhook::verify` contrôle la signature et l'horodatage d'une livraison de [webhook](/docs/fr/concepts/webhooks) avec le secret `whsec_` du endpoint, puis renvoie l'événement analysé. Passez le corps exactement tel qu'il est arrivé :

```php
use BillionSend\Exception\WebhookVerificationError;
use BillionSend\Webhook;

try {
    $event = Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('BILLIONSEND_WEBHOOK_SECRET'));
} catch (WebhookVerificationError) {
    http_response_code(400);
    exit;
}
if ($event['type'] === 'email.bounced') {
    // ...
}
```

Une livraison de plus de cinq minutes est refusée, et pendant la rotation d'un secret, l'un ou l'autre secret est accepté.

## Inscription d'un agent

```php
$signup = (new BillionSend\Client())->agent->signup(['human_email' => 'owner@acme.dev', 'name' => 'Support agent']);
echo $signup['inbox']['email_address'], "\n";
```

L'appel n'a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir [Inscription d'un agent](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
