Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

SDK Node.js

Envoyez des e-mails, gérez une boîte de réception et vérifiez des webhooks avec @billionsend/node, sur Node.js et TypeScript : toute l'API et l'idempotence.

Le paquet @billionsend/node est le client BillionSend pour Node.js et TypeScript. Il couvre toutes les opérations de la référence de l’API : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs conversations et brouillons, événements de boîte de réception en direct et inscription d’agents. Ses types viennent du document OpenAPI de l’API. Le code source est billionsend/billionsend-node sur GitHub.

Installation

Node 18 ou plus récent est requis. Le paquet n’a aucune dépendance et fournit à la fois des modules ES et du CommonJS.

npm install @billionsend/node

Envoyer un 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: ["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_...") prend directement la clé ; new BillionSend({ apiKey, baseUrl, timeoutMs, maxRetries, fetch }) règle le reste. BILLIONSEND_BASE_URL remplace l’URL de l’API.

Idempotence et nouvelles tentatives

Les méthodes d’envoi (emails.send, emails.batch, réponses et transferts, inboxes.send, inboxes.drafts.send) envoient toujours une Idempotency-Key. Sans idempotencyKey de votre part, chaque appel reçoit une nouvelle clé aléatoire que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n’envoie donc jamais deux fois ; votre propre clé sécurise aussi une répétition venue d’un autre processus.

Les échecs qui valent une nouvelle tentative sont retentés deux fois par défaut (maxRetries) : 429, 5xx, délais dépassés, erreurs réseau, et le 409 concurrent_idempotent_requests répondu tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : les lectures, PUT et DELETE, et les méthodes d’envoi. Le client attend ce que demande retry-after, jusqu’à une minute, et sinon espace les tentatives de façon exponentielle.

Erreurs

Les méthodes ne lèvent jamais d’exception. Chacune se résout en { data, error, headers }, avec exactement l’un de data et error défini. error est une BillionSendError d’une classe propre à son type : ValidationError (400, 422), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, avec retryAfter en secondes), APIError (5xx), APIConnectionError et APITimeoutError (aucune réponse). Chacune porte statusCode, name (le nom d’erreur de l’API), message et requestId, le x-request-id de la réponse, qui est l’identifiant de la requête sur la page Journaux du tableau de bord.

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

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

listAll et les flux d’événements lèvent les mêmes erreurs, car ils ne peuvent pas en renvoyer une par élément.

La boîte de réception d’un agent

Attendez le nouveau courrier sur le flux d’événements, lisez-le et répondez dans son fil :

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

Le flux se reconnecte avec Last-Event-ID lorsque la connexion tombe et rejoue ce qu’il a manqué : aucun événement n’est perdu ; conservez opened.data.lastEventId pour reprendre lors d’une exécution ultérieure avec { lastEventId }. Un stream.gap arrive une seule fois lorsque le flux reprend à plus de 24 heures en arrière. Le flux d’une boîte se termine après la suppression ou l’expiration de cette boîte ; bs.inboxes.events.stream() suit toutes les boîtes de l’équipe.

Vérifier les webhooks

verifyWebhook vérifie la signature et l’horodatage d’une livraison de webhook avec le secret whsec_ de l’endpoint et renvoie l’événement analysé. Passez le corps exactement tel qu’il est arrivé :

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

Avec Express, lisez le corps avec express.raw({ type: "application/json" }) et passez req.body et req.headers. Une livraison de plus de cinq minutes est refusée (tolerance modifie ce délai), et pendant une rotation de secret, l’un ou l’autre secret est accepté.

Inscription d’un agent

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);

L’appel n’a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir Inscription d’un agent pour ce qu’un compte non réclamé peut faire.

Cette page vous a-t-elle été utile ?