SDK de Node.js
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.
El paquete @billionsend/node es el cliente de BillionSend para Node.js y TypeScript. Cubre todas las operaciones de la referencia de la API: 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, en GitHub.
Instalar
Requiere Node 18 o superior. El paquete no tiene dependencias e incluye tanto módulos ES como CommonJS.
npm install @billionsend/node
Enviar un email
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.
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, léelo y responde en su hilo:
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 con el secreto whsec_ del endpoint y devuelve el evento ya interpretado. Pasa el cuerpo exactamente como llegó:
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
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 para saber qué puede hacer una cuenta sin reclamar.