TypeScript SDK

@messagebird/sdk é o SDK TypeScript oficial para a Bird API. É totalmente tipado, apenas ESM e pronto para edge. Roda em Node.js 20.3+ e runtimes edge modernos (Cloudflare Workers, Vercel Edge, Deno) usando APIs web padrão (fetch, AbortSignal, Web Crypto). Esta página cobre o cliente. Para enviar e-mail com o SDK, comece pelo quickstart de e-mail com TypeScript.

Instalação

Exemplo de código

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

O pacote é publicado como @messagebird/sdk no npm, a partir de messagebird/bird-sdk-typescript.

Construir um cliente

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

Apenas apiKey é obrigatório. A região é inferida a partir do prefixo bk_{region}_ da chave (uma chave bk_eu1_… direciona para https://eu1.platform.bird.com), então a maioria dos clientes é construída apenas com a chave. Consulte inferência de região para as regras de resolução. Você também pode definir padrões de canal na construção (por exemplo, email: { from: "hello@acme.com" } torna from opcional em cada envio) e o segredo de assinatura de webhook via webhooks: { secret }.

Primeira chamada

Exemplo 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 resolve diretamente para o resultado API, que neste exemplo é uma mensagem de e-mail com seu ID em_*. Para um passo a passo executável, siga o quickstart de TypeScript.

Design em duas camadas

O SDK tem uma camada gerada e uma camada escrita manualmente. Tipos de protocolo e a estrutura HTTP de baixo nível são gerados a partir da especificação OpenAPI da Bird, mantendo os formatos de solicitação e resposta alinhados com o contrato. A camada escrita manualmente fornece bird.email.send(...), tentativas, idempotência, paginação e erros. Campos de protocolo passam em snake_case (category, created_at); identificadores definidos pelo SDK, como nomes de métodos e idempotencyKey, usam camelCase. Os SDKs de Go e Python compartilham essa arquitetura. Consulte conceitos do SDK para mais detalhes.

Idempotência e tentativas automáticas

Cada mutação (POST, PUT, PATCH, DELETE) recebe um cabeçalho Idempotency-Key gerado automaticamente. O SDK reutiliza essa chave em cada nova tentativa, para que solicitações correspondentes possam reproduzir a resposta mantida. Para chaves personalizadas entre chamadas separadas ao SDK e limites de reprodução, consulte Idempotência.

As tentativas estão ativadas por padrão (maxRetries: 2). O cliente tenta novamente em falhas de rede, timeouts por tentativa e status transitórios (408, 429, 500, 502, 503, 504) com backoff exponencial com jitter, respeitando o cabeçalho Retry-After do servidor quando presente. Falhas determinísticas (4xx como 401, 404, 422) nunca são tentadas novamente. Defina maxRetries: 0 para desativar, ou sobrescreva por chamada. O ciclo de vida completo está descrito em conceitos do SDK.

Erros

Os métodos lançam exceção em caso de falha com uma hierarquia tipada que você restringe com instanceof. BirdError é a raiz. BirdAPIError cobre toda resposta de erro do servidor, com uma subclasse por type de erro. Incluem BirdAuthError (401), BirdRateLimitError (429, com retryAfter), BirdValidationError (422, com details por campo) e BirdPayloadTooLargeError (413). Falhas de transporte sem resposta HTTP usam as classes irmãs BirdConnectionError e BirdTimeoutError.

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

Todo BirdAPIError carrega statusCode, type, code (o código de erro E##### estável), requestId e docUrl. Ramifique pela classe (ou pelo type genérico) para fluxo de controle; use code quando precisar identificar uma falha específica. Prefere ramificar por valor em vez de capturar? Toda chamada também tem .safe():

Exemplo 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 a assinatura Standard Webhooks de uma entrega recebida e retorna um evento tipado e discriminado. Passe o corpo bruto da solicitação porque parsear e re-serializar altera os bytes assinados. Uma assinatura inválida, timestamp expirado ou cabeçalhos malformados lançam BirdWebhookVerificationError. Consulte verificação de webhook para o contrato entre SDK e Webhooks para a configuração na plataforma.

Próximos passos

Quickstart de e-mail: Use send, get, list, padrões de canal e os formatos de resposta.
Conceitos do SDK: Saiba mais sobre idempotência, tentativas, paginação, regiões e webhooks em todos os SDKs Bird.
Referência do API: Revise a HTTP API subjacente. bird.request<T>() alcança endpoints que a superfície tipada ainda não cobre, com a mesma autenticação, tentativas e idempotência.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Obtenha um resumo de implementação