PHP-SDK
E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Paket billionsend-php: jede API-Operation, Wiederholungen und Idempotenzschlüssel.
Das Paket billionsend/billionsend-php ist der BillionSend-Client für PHP. Es deckt jede Operation der API-Referenz ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Der Quellcode liegt auf GitHub unter billionsend/billionsend-php.
Installation
Erfordert PHP 8.1 oder neuer mit den Erweiterungen curl und json, sonst nichts.
composer require billionsend/billionsend-php
E-Mail senden
use BillionSend\Client;
$client = new Client(); // liest 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_...') nimmt den Schlüssel direkt entgegen. Das zweite Argument legt den Rest fest: 'base_url', 'timeout' (Sekunden pro Versuch, Standard 60), 'max_retries', 'headers' und 'transport' (jeder BillionSend\Transport, um über Ihren eigenen HTTP-Stack zu senden). BILLIONSEND_BASE_URL überschreibt die API-URL.
Methodennamen
Jede Operation ist eine Methode, benannt nach ihrer ID in der API-Referenz, der durch Punkte getrennte Pfad als Kette von Services: emails.send ist $client->emails->send(), emails.receiving.attachments.list ist $client->emails->receiving->attachments->list(). emails.metrics ist $client->emails->metrics->get(), neben ->links(), ->countries() und ->clients().
Eine Methode nimmt die Pfadparameter der Reihe nach, den Request-Body, die Query- und Header-Parameter und danach die Optionen des Aufrufs. Bodies und Antworten sind assoziative Arrays mit den Feldnamen der API, sodass die API-Referenz sie Feld für Feld beschreibt.
Idempotenz und Wiederholungsversuche
Die acht Versand-Operationen (emails->send, emails->batch, Antworten und Weiterleitungen auf empfangene Mails, inboxes->send, inboxes->drafts->send, Thread-Antworten und -Weiterleitungen) senden immer einen Idempotency-Key. Ohne 'idempotency_key' denkt sich jeder Aufruf einen aus, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.
Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler und das 409 concurrent_idempotent_requests, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: GET, PUT, DELETE und die Versand-Operationen. Der Client wartet so lange, wie Retry-After es verlangt, bis zu einer Minute, und weicht sonst exponentiell von 0,5 s bis 8 s zurück. Das letzte Argument jeder Methode nimmt 'idempotency_key', 'headers', 'timeout', 'max_retries' und 'response_headers' => &$headers für diesen Aufruf entgegen.
Fehler
Ein fehlgeschlagener Aufruf wirft ValidationError (400, 422), AuthenticationError (401 oder kein Schlüssel konfiguriert), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, mit getRetryAfter() in Sekunden), APIError (5xx), APIConnectionError (keine Antwort) oder APITimeoutError (der Versuch hat das Zeitlimit überschritten). Alle liegen in BillionSend\Exception und erweitern BillionSendError, mit getStatusCode(), getErrorName() (dem Fehlernamen der API), getMessage() und getRequestId(), dem x-request-id der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.
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()));
}
Listen
Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem einen ...All()-Generator, der die nächsten Seiten nach und nach abruft, rückwärts, wenn 'before' gesetzt ist:
foreach ($client->contacts->listAll(['limit' => 100]) as $contact) {
echo $contact['email'], "\n";
}
Das Postfach eines Agenten
Warten Sie im Ereignis-Stream auf neue Mails und antworten Sie in ihrem Thread:
use BillionSend\StreamGapEvent;
$stream = $client->inboxes->events->streamInbox('support@acme.dev', ['types' => 'inbox.email.received']);
foreach ($stream as $event) {
if ($event instanceof StreamGapEvent) {
continue; // Ereignisse können fehlen: Threads erneut lesen
}
$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']}"],
);
}
Der Stream verbindet sich mit Last-Event-ID neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie $stream->lastEventId() und übergeben Sie es als Option 'last_event_id' zurück, um nach einem Neustart fortzusetzen. Ein StreamGapEvent kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. Die Optionen 'max_reconnects' (Standard 5), 'reconnect_delay' und 'reconnect' => false steuern das Wiederverbinden. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. $client->inboxes->events->stream() folgt jedem Postfach, das der Schlüssel lesen kann.
Webhooks verifizieren
Webhook::verify prüft Signatur und Zeitstempel einer Webhook-Zustellung mit dem whsec_-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist:
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') {
// ...
}
Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt, und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.
Agent-Registrierung
$signup = (new BillionSend\Client())->agent->signup(['human_email' => 'owner@acme.dev', 'name' => 'Support agent']);
echo $signup['inbox']['email_address'], "\n";
Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter Agent-Registrierung.