---
title: SDK de Node.js
description: "Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Node.js y TypeScript con @billionsend/node: toda la API, reintentos e idempotencia."
ai:
  exclude: true
---

El paquete `@billionsend/node` es el cliente de BillionSend para Node.js y TypeScript. Cubre todas las operaciones de la [referencia de la API](/docs/es/api-reference): envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. Sus tipos salen del documento OpenAPI de la API. El código fuente está en [billionsend/billionsend-node](https://github.com/billionsend/billionsend-node), en GitHub.

## Instalar

Requiere Node 18 o superior. El paquete no tiene dependencias e incluye tanto módulos ES como CommonJS.

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

## Enviar un email

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

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

const { data, error } = await bs.emails.send(
  {
    from: "Acme <hello@acme.dev>",
    to: ["success@simulator.amazonses.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_...")` recibe la clave directamente; `new BillionSend({ apiKey, baseUrl, timeoutMs, maxRetries, fetch })` define el resto. `BILLIONSEND_BASE_URL` sustituye la URL de la API.

## Idempotencia y reintentos

Los métodos de envío (`emails.send`, `emails.batch`, respuestas y reenvíos, `inboxes.send`, `inboxes.drafts.send`) siempre mandan un `Idempotency-Key`. Si no pasas un `idempotencyKey` propio, cada llamada recibe una clave aleatoria nueva que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.

Los fallos que merecen otro intento se reintentan dos veces por defecto (`maxRetries`): 429, 5xx, timeouts, errores de red y el `409 concurrent_idempotent_requests` que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: lecturas, `PUT`, `DELETE` y los métodos de envío. El cliente espera lo que pida `retry-after`, hasta un minuto; si no, aumenta la espera de forma exponencial.

## Errores

Los métodos nunca lanzan excepciones. Cada uno devuelve `{ data, error, headers }`, con exactamente uno de `data` y `error` rellenado. `error` es un `BillionSendError` de una clase para cada tipo: `ValidationError` (400, 422), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, con `retryAfter` en segundos), `APIError` (5xx), `APIConnectionError` y `APITimeoutError` (sin respuesta). Cada uno trae `statusCode`, `name` (el nombre del error de la API), `message` y `requestId`, el `x-request-id` de la respuesta, que es el id de la petición en la página Registros del panel.

```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` y los flujos de eventos lanzan esos mismos errores, porque no pueden devolver uno por elemento.

## La bandeja de entrada de un agente

Espera email nuevo en el [flujo de eventos](/docs/es/inboxes), léelo y responde en su hilo:

```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; // puede faltar algún evento: vuelve a leer los hilos
  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}` },
  );
}
```

El flujo se reconecta con `Last-Event-ID` cuando se corta la conexión y reenvía lo que se perdió, así que no se pierde ningún evento. Guarda `opened.data.lastEventId` para retomarlo en una ejecución posterior con `{ lastEventId }`. Un `stream.gap` llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; `bs.inboxes.events.stream()` sigue todas las bandejas del equipo.

## Verificar webhooks

`verifyWebhook` comprueba la firma y la marca de tiempo de una entrega de [webhook](/docs/es/concepts/webhooks) con el secreto `whsec_` del endpoint y devuelve el evento ya interpretado. Pasa el cuerpo exactamente como llegó:

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

Con Express, lee el cuerpo con `express.raw({ type: "application/json" })` y pasa `req.body` y `req.headers`. Una entrega de más de cinco minutos se rechaza (`tolerance` lo cambia) y, durante la rotación de un secreto, sirve cualquiera de los dos.

## Registro 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);
```

La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta [Registro de agentes](/docs/es/agent-signup) para saber qué puede hacer una cuenta sin reclamar.
