TypeScript SDK

@messagebird/sdk es el SDK oficial de TypeScript para la API de Bird. Tiene tipos completos, es solo ESM y está listo para el edge. Se ejecuta en Node.js 20.3+ y entornos edge modernos (Cloudflare Workers, Vercel Edge, Deno) usando APIs web estándar (fetch, AbortSignal, Web Crypto). Esta página cubre el cliente. Para enviar correo electrónico con el SDK, comienza con el inicio rápido de email en TypeScript.

Instalación

Ejemplo de código

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

El paquete se publica como @messagebird/sdk en npm, desde messagebird/bird-sdk-typescript.

Construir un cliente

Ejemplo de código

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

Solo apiKey es obligatorio. La región se infiere del prefijo bk_{region}_ de la clave (una clave bk_eu1_… se dirige a https://eu1.platform.bird.com), así que la mayoría de los clientes se construyen solo con la clave. Consulta inferencia de región para las reglas de resolución. También puedes establecer valores predeterminados de canal en la construcción (por ejemplo, email: { from: "hello@acme.com" } hace que from sea opcional en cada envío) y el secreto de firma de webhooks mediante webhooks: { secret }.

Primera llamada

Ejemplo de código

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 resuelve directamente al resultado API, que en este ejemplo es un mensaje de correo electrónico con su ID em_*. Para un recorrido ejecutable, sigue el inicio rápido de TypeScript.

Diseño de dos capas

El SDK tiene una capa generada y una capa escrita a mano. Los tipos del protocolo y la infraestructura de bajo nivel de HTTP se generan a partir de la especificación OpenAPI de Bird, manteniendo las formas de solicitud y respuesta alineadas con el contrato. La capa escrita a mano proporciona bird.email.send(...), reintentos, idempotencia, paginación y errores. Los campos del protocolo se transmiten en snake_case (category, created_at); los identificadores definidos por SDK, como nombres de métodos y idempotencyKey, usan camelCase. Los SDKs de Go y Python comparten esta arquitectura. Consulta conceptos de SDK para más detalles.

Idempotencia y reintentos automáticos

Cada mutación (POST, PUT, PATCH, DELETE) recibe una cabecera Idempotency-Key generada automáticamente. El SDK reutiliza esa clave en cada reintento para que las solicitudes coincidentes puedan reproducir la respuesta conservada. Para claves personalizadas entre llamadas independientes al SDK y límites de reproducción, consulta Idempotencia.

Los reintentos están activados por defecto (maxRetries: 2). El cliente reintenta fallos de red, tiempos de espera por intento y estados transitorios (408, 429, 500, 502, 503, 504) con backoff exponencial con jitter, respetando el encabezado Retry-After del servidor cuando está presente. Los fallos deterministas (4xx como 401, 404, 422) nunca se reintentan. Establece maxRetries: 0 para desactivar, o sobrescríbelo por llamada. El ciclo de vida completo se describe en conceptos de SDK.

Errores

Los métodos lanzan una excepción en caso de fallo con una jerarquía tipada que reduces con instanceof. BirdError es la raíz. BirdAPIError cubre cada respuesta de error del servidor, con una subclase por type de error. Estas incluyen BirdAuthError (401), BirdRateLimitError (429, con retryAfter), BirdValidationError (422, con details por campo) y BirdPayloadTooLargeError (413). Los fallos de transporte sin respuesta HTTP usan las clases hermanas BirdConnectionError y BirdTimeoutError.

Ejemplo de código

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

Cada BirdAPIError contiene statusCode, type, code (el código de error estable de E#####), requestId y docUrl. Ramifica según la clase (o el type general) para el flujo de control; usa code cuando necesites identificar un fallo específico. ¿Prefieres ramificar por valor en lugar de capturar? Cada llamada también tiene .safe():

Ejemplo de código

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) verifica la firma de Standard Webhooks de una entrega entrante y devuelve un evento tipado y discriminado. Pasa el cuerpo crudo de la solicitud porque analizar y re-serializar cambia los bytes firmados. Una firma inválida, una marca de tiempo obsoleta o encabezados malformados lanzan BirdWebhookVerificationError. Consulta verificación de webhooks para el contrato entre SDK y Webhooks para la configuración de la plataforma.

Próximos pasos

Inicio rápido de email: Usa send, get, list, valores predeterminados de canal y las formas de respuesta.
Conceptos de SDK: Aprende sobre idempotencia, reintentos, paginación, regiones y webhooks en todos los SDKs de Bird.
Referencia de API: Revisa la API de HTTP subyacente. bird.request<T>() alcanza endpoints que la superficie tipada aún no cubre, con la misma autenticación, reintentos e idempotencia.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Obtener un resumen de implementación