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

Codebeispiel

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

Codebeispiel

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

Codebeispiel

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 verwaltete 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(...), Retries, 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- und Python-SDKs teilen diese Architektur. Siehe SDK-Konzepte für Details.

Automatische Idempotenz und Retries

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.

Retries sind standardmäßig aktiviert (maxRetries: 2). Der Client wiederholt Netzwerkfehler, Timeouts pro Versuch und transiente Statuscodes (408, 429, 500, 502, 503, 504) mit exponentiellem Backoff und Jitter und berücksichtigt dabei den Retry-After-Header des Servers, sofern vorhanden. Deterministische Fehler (4xx wie 401, 404, 422) werden nie wiederholt. Setzen Sie maxRetries: 0, um Retries 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.

Codebeispiel

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 nach der Klasse (oder dem groben type) für den Kontrollfluss; verwenden Sie code, wenn Sie einen bestimmten Fehler abgleichen müssen. Lieber nach einem Wert verzweigen statt zu fangen? Jeder Aufruf bietet auch .safe():

Codebeispiel

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, Retries, 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 Retries und derselben Idempotenz.

Verwandte Ressourcen