---
title: PHP-SDK
description: "E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Paket billionsend-php: jede API-Operation, Wiederholungen und Idempotenzschlüssel."
ai:
  exclude: true
---

Das Paket `billionsend/billionsend-php` ist der BillionSend-Client für PHP. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) 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](https://github.com/billionsend/billionsend-php).

## Installation

Erfordert PHP 8.1 oder neuer mit den Erweiterungen `curl` und `json`, sonst nichts.

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

## E-Mail senden

```php
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](/docs/de/api-reference), 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.

```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()));
}
```

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

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

## Das Postfach eines Agenten

Warten Sie im [Ereignis-Stream](/docs/de/inboxes) auf neue Mails und antworten Sie in ihrem Thread:

```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; // 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](/docs/de/concepts/webhooks)-Zustellung mit dem `whsec_`-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist:

```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') {
    // ...
}
```

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

```php
$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](/docs/de/agent-signup).
