TypeScript SDK

@messagebird/sdk ist das offizielle TypeScript SDK für die Bird API. Es ist vollständig typisiert, ESM-only und edge-ready. Es läuft auf Node.js 20.3+ und modernen Edge-Runtimes (Cloudflare Workers, Vercel Edge, Deno) mit webstandardisierten APIs (fetch, AbortSignal, Web Crypto). Diese Seite behandelt den Client. Um E-Mails mit dem SDK zu senden, starten Sie mit dem TypeScript-E-Mail-Quickstart.

Installieren

npm install @messagebird/sdk
# pnpm add @messagebird/sdk
# yarn add @messagebird/sdk
# bun add @messagebird/sdk

Das Paket ist als @messagebird/sdk auf npm veröffentlicht, aus messagebird/bird-sdk-typescript.

Client erstellen

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  region: "eu1", // optional; overrides the region from the key prefix
  baseUrl: "http://localhost:8080", // optional; overrides region (local or self-hosted)
  timeout: 60_000, // per-attempt timeout in ms (default 60_000)
  maxRetries: 2, // retry budget for transient failures (default 2)
});

Nur apiKey ist erforderlich. Die Region wird aus dem bk_{region}_-Präfix des Schlüssels abgeleitet (ein bk_eu1_…-Schlüssel leitet zu https://eu1.platform.bird.com), sodass die meisten Clients nur mit dem Schlüssel erstellt werden. Siehe Regionserkennung für die Auflösungsregeln. Sie können beim Erstellen auch Kanalstandardwerte setzen (z. B. macht email: { from: "hello@acme.com" } from bei jedem Versand optional) und das Webhook-Signaturgeheimnis über webhooks: { secret } festlegen.

Erster Aufruf

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

await gibt direkt das API-Ergebnis zurück, in diesem Beispiel eine E-Mail-Nachricht mit ihrer em_*-ID. Für eine ausführbare Anleitung folgen Sie dem TypeScript-Quickstart.

Zweischicht-Design

Das SDK hat eine generierte Schicht und eine manuell gepflegte Schicht. Wire-Typen und die Low-Level-HTTP-Infrastruktur werden aus der OpenAPI-Spezifikation von Bird generiert, sodass Request- und Response-Strukturen mit dem Vertrag übereinstimmen. Die manuell geschriebene Schicht stellt bird.email.send(...), erneute Versuche, Idempotenz, Paginierung und Fehler bereit. Wire-Felder werden in snake_case durchgereicht (category, created_at); SDK-definierte Bezeichner wie Methodennamen und idempotencyKey verwenden camelCase. Die Go-, Python- und PHP-SDKs teilen diese Architektur. Details finden Sie unter SDK-Konzepte.

Automatische Idempotenz und erneute Versuche

Jede Mutation (POST, PUT, PATCH, DELETE) erhält einen automatisch erzeugten Header Idempotency-Key. Das SDK verwendet diesen Schlüssel bei jedem Wiederholungsversuch erneut, damit übereinstimmende Anfragen die gespeicherte Antwort erneut erhalten können. Hinweise zu eigenen Schlüsseln über separate SDK-Aufrufe hinweg und zu Wiedergabegrenzen finden Sie unter Idempotenz.

Erneute Versuche sind standardmäßig aktiviert (maxRetries: 2). Der Client versucht Netzwerkfehler, Timeouts pro Versuch und transiente Statuscodes (408, 429, 500, 502, 503, 504) mit exponentiellem Backoff und Jitter erneut und berücksichtigt dabei den Retry-After-Header des Servers, sofern vorhanden. Deterministische Fehler (4xx wie 401, 404, 422) werden nie erneut versucht. Setzen Sie maxRetries: 0, um erneute Versuche zu deaktivieren, oder überschreiben Sie die Einstellung pro Aufruf. Der vollständige Lebenszyklus ist unter SDK-Konzepte beschrieben.

Fehler

Methoden werfen bei Fehlern eine typisierte Hierarchie, die Sie mit instanceof eingrenzen. BirdError ist die Wurzelklasse. BirdAPIError deckt jede Fehlerantwort des Servers ab, mit einer Unterklasse pro Fehler-type. Dazu gehören BirdAuthError (401), BirdRateLimitError (429, mit retryAfter), BirdValidationError (422, mit feldspezifischen details) und BirdPayloadTooLargeError (413). Transportfehler ohne HTTP-Antwort verwenden die Geschwisterklassen BirdConnectionError und BirdTimeoutError.

import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Jeder BirdAPIError enthält statusCode, type, code (den stabilen E#####-Fehlercode), requestId und docUrl. Verzweigen Sie für den Kontrollfluss nach der Klasse (oder dem groben type); verwenden Sie code, wenn Sie einen bestimmten Fehler abgleichen müssen. Um nach einem Wert zu verzweigen, statt Ausnahmen abzufangen, rufen Sie .safe() auf:

const { data, error } = await bird.email
  .send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  })
  .safe();
if (error) console.error(error.message);
else console.log(data.id);

Webhooks

bird.webhooks.unwrap(rawBody, headers) verifiziert die Standard-Webhooks-Signatur einer eingehenden Zustellung und gibt ein typisiertes, diskriminiertes Event zurück. Übergeben Sie den rohen Request-Body, da Parsen und erneutes Serialisieren die signierten Bytes verändert. Eine ungültige Signatur, ein abgelaufener Zeitstempel oder fehlerhafte Header lösen BirdWebhookVerificationError aus. Siehe Webhook-Verifizierung für den SDK-übergreifenden Vertrag und Webhooks für die Plattformeinrichtung.

Nächste Schritte

• E-Mail-Quickstart: Verwenden Sie send, get, list, Kanalstandardwerte und die Response-Strukturen.
• SDK-Konzepte: Erfahren Sie mehr über Idempotenz, erneute Versuche, Paginierung, Regionen und Webhooks über alle Bird-SDKs hinweg.
• API-Referenz: Sehen Sie sich die zugrunde liegende HTTP API an. bird.request<T>() erreicht Endpunkte, die die typisierte Oberfläche noch nicht abdeckt, mit derselben Authentifizierung, denselben erneuten Versuchen und derselben Idempotenz.