Sign inGet Started

SDK-Konzepte

Die SDKs für TypeScript, Go, Python und PHP folgen einem gemeinsamen Design. Jedes besitzt eine generierte Basis mit Typen und einen Low-Level-Client, der aus der OpenAPI-Spezifikation von Bird erzeugt wird. Eine manuell geschriebene Schicht verwaltet den Request-Lebenszyklus und stellt die kuratierte Oberfläche bereit. Diese Seite behandelt das gemeinsame Verhalten. Die sprachspezifischen Seiten behandeln idiomatische Details.

Auto-Idempotenz

Jede Mutation (POST, PUT, PATCH, DELETE) erhält einen automatisch generierten Idempotency-Key-Header. Der Schlüssel wird einmal pro logischem Aufruf erzeugt und bei jedem Wiederholungsversuch wiederverwendet. Das verhindert, dass ein wiederholter Schreibvorgang doppelt ausgeführt wird. Wenn ein Senden nach der serverseitigen Verarbeitung in ein Timeout läuft, erhält der Wiederholungsversuch die gespeicherte Antwort. Übergeben Sie Ihren eigenen Schlüssel (pro Aufruf idempotencyKey / option.WithIdempotencyKey / idempotency_key), wenn die logische Operation mehr als einen SDK-Aufruf umfasst, z. B. eine anwendungsseitige Wiederholungsschleife um den SDK. Siehe Idempotenz für das serverseitige Protokoll.

Sichere Wiederholungsversuche

Wiederholungsversuche sind standardmäßig aktiviert (maxRetries: 2 in jedem SDK). Der Client wiederholt transiente Fehler, darunter Netzwerkfehler, Timeouts pro Versuch, 429-Antworten und wiederholbare 5xx-Antworten. Er verwendet Exponential Backoff mit Jitter und berücksichtigt den Retry-After-Header des Servers. Deterministische Fehler (401, 404, 422 und andere 4xx-Antworten) werden nie wiederholt. Die Wiederverwendung des Idempotenz-Schlüssels macht Mutations-Wiederholungen sicher. Das Timeout gilt pro Versuch (standardmäßig 60 Sekunden), sodass ein Aufruf mit Wiederholungen länger dauern kann. PHP verwendet das Timeout des injizierten HTTP-Clients, da PSR-18 kein portables Timeout pro Request bietet.

Paginierung

Listen-Endpunkte sind cursor-paginiert. Jeder SDK unterstützt native Iteration, die aufeinanderfolgende Seiten automatisch abruft. Für manuelle Cursor-Steuerung verwenden Sie den Einzelseiten-Accessor. Jede Seite enthält data und next_cursor; übergeben Sie den Cursor als starting_after, um weiterzublättern.
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
Siehe die Paginierungsreferenz für Cursor, limit und include_total.

Regionserkennung

Bird API-Schlüssel codieren ihre Region: bk_{region}_{token}. Der SDK liest das Präfix und routet automatisch zu https://{region}.platform.bird.com. Eine region-Option überschreibt die erkannte Region. Eine explizite baseUrl (option.WithBaseURL / base_url) hat Vorrang vor beidem und unterstützt lokale Entwicklung oder selbst gehostete Deployments. Die Konstruktion schlägt fehl, wenn der Schlüssel nicht dem bk_{region}_-Format entspricht und kein Override gesetzt ist.

Optionen pro Aufruf vs. reine Konstruktionskonfiguration

Die Konfiguration hat zwei Ebenen. Identitäts- und Transporteinstellungen gelten nur bei der Konstruktion: der API-Schlüssel, die Base-URL oder Region und der HTTP-Client oder die fetch-Implementierung. Lebenszyklus-Einstellungen können als Konstruktionsstandards gesetzt und pro Aufruf überschrieben werden: timeout, maxRetries, der Idempotenz-Schlüssel und zusätzliche Header. TypeScript, Python und PHP verwenden ein nachgestelltes Options-Objekt; Go verwendet variadische option.With…-Optionen. Von SDK verwaltete Header (Authorization, User-Agent, Idempotency-Key) haben Vorrang vor vom Aufrufer übergebenen Headern. Kanal-Standardwerte, wie z. B. ein Standard-E-Mail-from, folgen demselben Muster.

Webhook-Verifizierung

Jedes SDK stellt einen Verifizierungs-Einstiegspunkt bereit: webhooks.unwrap(rawBody, headers). Es implementiert Standard Webhooks mit HMAC-SHA256 über den rohen Payload und das Signing Secret Ihres Endpunkts. Es akzeptiert v1-getaggte Signatureinträge, lehnt Zeitstempel außerhalb eines 5-Minuten-Toleranzfensters ab und vergleicht Signaturen in konstanter Zeit. Übergeben Sie die rohen Request-Body-Bytes exakt wie empfangen. Das Parsen und erneute Serialisieren des JSON verändert die Bytes und macht die Signatur ungültig.
Bei Erfolg gibt unwrap ein typisiertes Event zurück, unterschieden anhand von type, z. B. email.delivered oder email.bounced. Unbekannte Event-Typen werden trotzdem verifiziert und decodiert, behandeln Sie sie also in Ihrem default-Branch. Ein Verifizierungsfehler ist ein eigener Fehlertyp (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); antworten Sie mit 400. Siehe Webhooks für die Endpunkt-Einrichtung und den Event-Katalog.

Nächste Schritte

  • Schnellstarts: Senden Sie Ihre erste E-Mail in Ihrer Sprache und Ihrem Framework.
  • Webhooks und Events: Richten Sie einen Endpunkt ein und erkunden Sie den Event-Katalog hinter unwrap.
  • API-Referenz: Sehen Sie sich den HTTP-Vertrag an, den jedes SDK verwendet.