SDK PHP
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.
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 : 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.
Installer
Nécessite PHP 8.1 ou plus récent avec les extensions curl et json, et rien d’autre.
composer require billionsend/billionsend-php
Envoyer un e-mail
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, 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.
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 :
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 et répondez dans leur fil :
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 avec le secret whsec_ du endpoint, puis renvoie l’événement analysé. Passez le corps exactement tel qu’il est arrivé :
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
$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 pour ce qu’un compte non réclamé peut faire.