---
title: SDK para Node.js
description: Use o BillionSend em Node.js e TypeScript com o pacote @billionsend/node.
ai:
  exclude: true
---

O pacote `@billionsend/node` é o cliente do BillionSend para Node.js e TypeScript. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): envio, domínios, contatos, broadcasts, templates, webhooks, caixas de entrada com suas conversas e rascunhos, eventos das caixas de entrada em tempo real e cadastro de agentes. Os tipos vêm do documento OpenAPI da API. O código-fonte está em [billionsend/billionsend-node](https://github.com/billionsend/billionsend-node) no GitHub.

## Instalar

Precisa do Node 18 ou mais novo. O pacote não tem dependências e traz tanto ES modules quanto CommonJS.

```sh
npm install @billionsend/node
```

## Enviar um e-mail

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send(
  {
    from: "Acme <hello@acme.dev>",
    to: ["ana@example.com"],
    subject: "Welcome to Acme",
    html: "<p>Glad you are here.</p>",
  },
  { idempotencyKey: "welcome/ana" },
);

if (error) console.error(error.statusCode, error.name, error.message, error.requestId);
else console.log(data.id);
```

`new BillionSend("bs_...")` recebe a chave diretamente; `new BillionSend({ apiKey, baseUrl, timeoutMs, maxRetries, fetch })` define o resto. `BILLIONSEND_BASE_URL` substitui a URL da API.

## Idempotência e novas tentativas

Os métodos de envio (`emails.send`, `emails.batch`, respostas e encaminhamentos, `inboxes.send`, `inboxes.drafts.send`) sempre mandam um `Idempotency-Key`. Sem um `idempotencyKey` seu, cada chamada recebe uma chave aleatória nova que as novas tentativas dela reutilizam, então repetir depois de um timeout nunca envia duas vezes; uma chave sua também deixa segura a repetição vinda de outro processo.

As falhas que valem nova tentativa são repetidas duas vezes por padrão (`maxRetries`): 429, 5xx, timeouts, erros de rede e o `409 concurrent_idempotent_requests` respondido enquanto a primeira tentativa com a mesma chave ainda está em andamento. Só se repetem requisições seguras de repetir: leituras, `PUT` e `DELETE`, e os métodos de envio. O cliente espera o que o `retry-after` pede, até um minuto, e senão espera cada vez mais entre as tentativas.

## Erros

Os métodos nunca lançam exceção. Cada um resolve para `{ data, error, headers }`, com exatamente um entre `data` e `error` preenchido. `error` é um `BillionSendError` de uma classe para cada tipo: `ValidationError` (400, 422), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, com `retryAfter` em segundos), `APIError` (5xx), `APIConnectionError` e `APITimeoutError` (sem resposta). Cada um traz `statusCode`, `name` (o nome do erro da API), `message` e `requestId`, o `x-request-id` da resposta, que é o id da requisição na página Logs do painel.

```ts
import { NotFoundError } from "@billionsend/node";

const { data, error } = await bs.emails.get(id);
if (error instanceof NotFoundError) return null;
if (error) throw error;
```

`listAll` e os streams de eventos lançam esses mesmos erros, já que não podem devolver um por item.

## A caixa de entrada de um agente

Espere e-mail novo no [stream de eventos](/docs/pt-br/inboxes), leia e responda na conversa:

```ts
const inbox = "support@acme.dev";
const opened = await bs.inboxes.events.streamInbox(inbox, { types: "inbox.email.received" });
if (opened.error) throw opened.error;

for await (const item of opened.data) {
  if (item.event === "stream.gap") continue; // events may be missing: read the threads again
  const { thread_id, email_id } = item.data.data;
  if (!thread_id || !email_id) continue;

  const email = await bs.inboxes.threads.emails.get(inbox, thread_id, email_id);
  if (email.error) throw email.error;

  await bs.inboxes.threads.emails.reply(
    inbox,
    thread_id,
    email_id,
    { text: await draftAnswer(email.data.text) },
    { idempotencyKey: `reply/${email_id}` },
  );
}
```

O stream reconecta com `Last-Event-ID` quando a conexão cai e reenvia o que perdeu, então nenhum evento se perde; guarde `opened.data.lastEventId` para retomar numa execução seguinte com `{ lastEventId }`. Um `stream.gap` chega uma vez quando o stream retoma de mais de 24 horas atrás. O stream de uma caixa termina depois que essa caixa é excluída ou expira; `bs.inboxes.events.stream()` acompanha todas as caixas da equipe.

## Verificar webhooks

`verifyWebhook` confere a assinatura e o horário de uma entrega de [webhook](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve o evento já lido. Passe o corpo exatamente como chegou:

```ts
import { verifyWebhook, WebhookVerificationError } from "@billionsend/node";

try {
  const event = await verifyWebhook(await request.text(), request.headers, process.env.BILLIONSEND_WEBHOOK_SECRET);
  if (event.type === "email.bounced") {
    // ...
  }
} catch (error) {
  if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
  throw error;
}
```

Com Express, leia o corpo com `express.raw({ type: "application/json" })` e passe `req.body` e `req.headers`. Uma entrega com mais de cinco minutos é recusada (`tolerance` muda isso) e, durante a rotação de um segredo, qualquer um dos dois verifica.

## Cadastro de agentes

```ts
const signup = await new BillionSend().agent.signup({
  human_email: "owner@acme.dev",
  name: "Support agent",
});
if (signup.data) console.log(signup.data.inbox.email_address);
```

A chamada não precisa de chave de API; a resposta traz a nova chave e a caixa de entrada. Veja [Cadastro de agentes](/docs/pt-br/agent-signup) para o que uma conta ainda não reivindicada pode fazer.
