SDK para Node.js
Use o BillionSend em Node.js e TypeScript com o pacote @billionsend/node.
O pacote @billionsend/node é o cliente do BillionSend para Node.js e TypeScript. Ele cobre todas as operações da referência da API: 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 no GitHub.
Instalar
Precisa do Node 18 ou mais novo. O pacote não tem dependências e traz tanto ES modules quanto CommonJS.
npm install @billionsend/node
Enviar um e-mail
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.
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, leia e responda na conversa:
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 com o segredo whsec_ do endpoint e devolve o evento já lido. Passe o corpo exatamente como chegou:
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
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 para o que uma conta ainda não reivindicada pode fazer.