Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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.

Esta página foi útil?