PHP SDK

messagebird/sdk ist das offizielle PHP SDK für die Bird API: eine typisierte, handgeschriebene Oberfläche über einer generierten Wire-Schicht. Es setzt PHP 8.2+ voraus und arbeitet synchron; HTTP läuft über jeden PSR-18-Client, den Sie bereits nutzen (Guzzle, Symfony HttpClient, …), und wird automatisch erkannt. Diese Seite behandelt den Client selbst; um eine E-Mail vollständig zu versenden, beginnen Sie mit dem PHP-E-Mail-Quickstart.

Installieren

composer require messagebird/sdk

Das Paket ist als messagebird/sdk auf Packagist veröffentlicht.

Client erstellen

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    region: 'eu1',                                          // optional; overrides the region inferred from the key prefix
    maxRetries: 2,                                          // retry budget for transient failures (default 2)
    email: new EmailDefaults(from: 'hello@acme.com'),       // optional channel defaults, such as a default sender
    webhookSecret: getenv('BIRD_WEBHOOK_SECRET') ?: null,   // signing secret for $bird->webhooks->unwrap()
);

Nur der API-Schlüssel ist erforderlich. Die Region wird aus dem bk_{region}_-Präfix des Schlüssels abgeleitet (ein bk_eu1_…-Schlüssel wird an https://eu1.platform.bird.com weitergeleitet), sodass die meisten Clients nur mit dem Schlüssel erstellt werden; die Regeln finden Sie unter Region-Ableitung. baseUrl überschreibt die Region vollständig (lokal oder selbstgehostet). Hier gesetzte Kanal-Standardwerte (zum Beispiel email: new EmailDefaults(from: "hello@acme.com")) machen dieses Feld bei jedem Senden optional, und webhookSecret ist das Secret, mit dem $bird->webhooks->unwrap() verifiziert. Konfigurieren Sie ein Timeout pro Anfrage auf dem PSR-18-Client, den Sie an Bird übergeben. PSR-18 hat kein portables Timeout, daher gehört die Einstellung dem Transport.

Erster Aufruf

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

Der Aufruf gibt das API-Ergebnis direkt zurück: hier eine E-Mail-Nachricht mit ihrer em_*-ID. Für eine ausführbare Anleitung folgen Sie dem PHP-Quickstart.

Zwei-Schichten-Design

Das SDK kombiniert generierte und handgepflegte Schichten. Die Wire-Typen unter MessageBird\Wire stammen aus der OpenAPI-Spezifikation von Bird über jane-php und halten Request- und Response-Strukturen vertragsgenau. Die handgeschriebene Schicht stellt $bird->email->send(...), Retries, Idempotenz, Paginierung, Fehler und Webhook-Verifizierung bereit. Wire-Felder werden in snake_case wörtlich durchgereicht, zum Beispiel category und created_at. Nur SDK-definierte Bezeichner, einschließlich Methoden- und Optionsnamen wie idempotencyKey, verwenden camelCase. Die TypeScript-, Go- und Python-SDKs teilen diese Architektur; siehe SDK-Konzepte.

Automatische Idempotenz und Retries

Jede Mutation (POST, PUT, PATCH, DELETE) erhält einen automatisch erzeugten Header Idempotency-Key. Derselbe Schlüssel wird bei jedem Wiederholungsversuch verwendet, damit übereinstimmende Anfragen die gespeicherte Antwort erneut erhalten können. Wiederholungsversuche sind standardmäßig aktiviert (maxRetries: 2): Der Client versucht vorübergehende Fehler (429, 5xx außer 501 und PSR-18-Transportfehler) mit exponentiell verlängerten, zufällig variierten Wartezeiten erneut und berücksichtigt den Header Retry-After des Servers. Deterministische Fehler (4xx wie 401, 404, 422) werden nicht erneut versucht. Hinweise zu eigenen Schlüsseln über separate SDK-Aufrufe hinweg und zu Wiedergabegrenzen finden Sie unter Idempotenz. Überschreiben Sie Idempotenz und Wiederholungsversuche pro Aufruf:

$bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
    options: new RequestOptions(idempotencyKey: 'order-1234', maxRetries: 0),
);

Fehler

Ein fehlgeschlagener Aufruf wirft eine Exception. MessageBird\Exception\ApiException deckt jede Fehlerantwort des Servers ab und enthält status (den HTTP-Status), type (die grobe Kategorie) und errorCode (den stabilen E#####-Code). Ein Transportfehler, der das Retry-Budget aufbraucht, wirft stattdessen MessageBird\Exception\ConnectionException, weil keine HTTP-Antwort existiert. Beide erweitern MessageBird\Exception\BirdException; fangen Sie diese ab, um beide Fälle zu behandeln.

try {
    $bird->email->send(
        from: 'Bird <onboarding@messagebird.dev>',
        to: ['delivered@messagebird.dev'],
        subject: 'Hello from Bird',
        html: '<p>My first Bird email.</p>',
    );
} catch (ApiException $e) {
    // The server returned an error response. $status is the HTTP status, $type
    // the coarse category, $errorCode the stable E##### code.
    echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
    // All retry attempts failed, so no HTTP response is available.
    echo 'transport error: ', $e->getMessage();
}

Paginierung

List-Methoden geben ein Lazy-Core\Page zurück; das Iterieren mit foreach paginiert automatisch über Cursor und lädt Seiten bei Bedarf:

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

Für manuelle Cursor-Steuerung gibt fetch() eine einzelne Seite zurück: ihre data plus den Vorwärts-nextCursor, den Sie als starting_after zurückgeben, um fortzufahren:

$page = $bird->email->list(['status' => 'delivered'])->fetch();
foreach ($page->data as $message) {
    echo $message->getId(), "\n";
}
$next = $page->nextCursor; // pass back as starting_after to fetch the next page

Escape Hatch

Endpunkte, die noch nicht auf der typisierten Oberfläche verfügbar sind, erreichen Sie über $bird->get / post / put / patch / delete, mit derselben Authentifizierung, denselben Retries, derselben Idempotenz und Base-URL-Behandlung:

// The verb methods (get/post/put/patch/delete) run through the same auth,
// retries, idempotency, and base-URL handling as the typed methods; pass a
// path and, for writes, a body array.
$messages = $bird->get('/v1/sms/messages', query: ['limit' => 10]);
$created = $bird->post('/v1/sms/messages', body: [
    'from' => '+15557654321',
    'to' => '+15551234567',
    'text' => 'Your code is 123456.',
    'category' => 'authentication',
]);

Die Pfade finden Sie in der API-Referenz.

Webhooks

Verifizieren Sie die Standard-Webhooks-Signatur eines empfangenen Webhooks und erhalten Sie das dekodierte Event. Setzen Sie das Signing-Secret auf dem Client (oder übergeben Sie es pro Aufruf) und übergeben Sie den rohen Request-Body: Die Signatur wird über die rohen Bytes berechnet, daher ist das Parsen vor dem Verifizieren der klassische Webhook-Fehler.

// Pass the raw request body because parsing changes the bytes used to compute
// the signature.
$rawBody = file_get_contents('php://input') ?: '';
try {
    $event = $bird->webhooks->unwrap($rawBody, getallheaders());
    // $event is the decoded payload as an array; branch on $event['type'].
    echo $event['type'];
} catch (WebhookVerificationError) {
    http_response_code(400); // bad signature, stale timestamp, or missing/malformed headers
}

Nächste Schritte

• PHP-E-Mail-Quickstart: ein ausführbarer End-to-End-Versand.
• SDK-Konzepte: das Retry-, Paginierungs- und Regionsmodell, das alle SDKs teilen.
• API-Referenz: jede Operation, mit PHP-Beispielen.