TypeScript SDK

@messagebird/sdk est le SDK TypeScript officiel pour l'API Bird. Il est entièrement typé, exclusivement ESM et prêt pour l'edge. Il fonctionne sur Node.js 20.3+ et les runtimes edge modernes (Cloudflare Workers, Vercel Edge, Deno) via les API web standard (fetch, AbortSignal, Web Crypto). Cette page couvre le client. Pour envoyer un e-mail avec le SDK, commencez par le quickstart e-mail TypeScript.

Installation

Exemple de code

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

Le paquet est publié sous le nom @messagebird/sdk sur npm, depuis messagebird/bird-sdk-typescript.

Construire un client

Exemple de code

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

Seul apiKey est requis. La région est déduite du préfixe bk_{region}_ de la clé (une clé bk_eu1_… est routée vers https://eu1.platform.bird.com), donc la plupart des clients sont construits avec la clé seule. Consultez l'inférence de région pour les règles de résolution. Vous pouvez aussi définir des valeurs par défaut de canal à la construction (par exemple email: { from: "hello@acme.com" } rend from optionnel à chaque envoi) et le secret de signature webhook via webhooks: { secret }.

Premier appel

Exemple de code

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 résout directement le résultat API, qui est un message e-mail avec son ID em_* dans cet exemple. Pour un guide exécutable, suivez le quickstart TypeScript.

Architecture à deux couches

Le SDK comporte une couche générée et une couche écrite manuellement. Les types réseau et la plomberie HTTP de bas niveau sont générés à partir de la spécification OpenAPI de Bird, ce qui maintient les formes de requêtes et de réponses alignées sur le contrat. La couche écrite manuellement fournit bird.email.send(...), les réessais, l'idempotence, la pagination et les erreurs. Les champs réseau passent en snake_case (category, created_at) ; les identifiants définis par SDK, tels que les noms de méthodes et idempotencyKey, utilisent camelCase. Les SDK Go et Python partagent cette architecture. Consultez les concepts SDK pour plus de détails.

Idempotence et réessais automatiques

Chaque mutation (POST, PUT, PATCH, DELETE) reçoit un en-tête Idempotency-Key généré automatiquement. Le SDK réutilise cette clé à chaque nouvelle tentative afin que les requêtes identiques puissent restituer la réponse conservée. Pour les clés personnalisées entre des appels distincts au SDK et les limites de restitution, consultez Idempotence.

Les réessais sont activés par défaut (maxRetries: 2). Le client réessaie les échecs réseau, les délais d'expiration par tentative et les statuts transitoires (408, 429, 500, 502, 503, 504) avec un backoff exponentiel à gigue, en respectant l'en-tête Retry-After du serveur lorsqu'il est présent. Les échecs déterministes (4xx tels que 401, 404, 422) ne sont jamais réessayés. Définissez maxRetries: 0 pour désactiver les réessais, ou surchargez par appel. Le cycle de vie complet est décrit dans les concepts SDK.

Erreurs

Les méthodes lèvent une exception en cas d'échec, avec une hiérarchie typée que vous affinez avec instanceof. BirdError est la racine. BirdAPIError couvre toute réponse d'erreur du serveur, avec une sous-classe par type d'erreur. Celles-ci incluent BirdAuthError (401), BirdRateLimitError (429, avec retryAfter), BirdValidationError (422, avec details par champ), et BirdPayloadTooLargeError (413). Les échecs de transport sans réponse HTTP utilisent les classes sœurs BirdConnectionError et BirdTimeoutError.

Exemple de code

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;
}

Chaque BirdAPIError porte statusCode, type, code (le code d'erreur E##### stable), requestId et docUrl. Branchez sur la classe (ou le type générique) pour le flux de contrôle ; utilisez code quand vous devez identifier un échec précis. Vous préférez brancher sur une valeur plutôt que capturer ? Chaque appel propose aussi .safe() :

Exemple de code

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) vérifie la signature Standard Webhooks d'une livraison entrante et renvoie un événement typé et discriminé. Passez le corps brut de la requête, car l'analyser puis le re-sérialiser modifie les octets signés. Une signature invalide, un horodatage périmé ou des en-têtes mal formés lèvent BirdWebhookVerificationError. Consultez la vérification de webhook pour le contrat cross-SDK et Webhooks pour la configuration de la plateforme.

Étapes suivantes

Quickstart e-mail : utilisez send, get, list, les valeurs par défaut de canal et les formes de réponse.
Concepts SDK : découvrez l'idempotence, les réessais, la pagination, les régions et les webhooks dans tous les SDK Bird.
Référence API : consultez l'API HTTP sous-jacente. bird.request<T>() atteint les endpoints que la surface typée ne couvre pas encore, avec la même authentification, les mêmes réessais et la même idempotence.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation