---
title: SDK Node.js
description: "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."
ai:
  exclude: true
---

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](/docs/fr/api-reference) : 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](https://github.com/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.

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

## Envoyer un e-mail

```ts
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.

```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` 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](/docs/fr/inboxes), lisez-le et répondez dans son fil :

```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; // 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](/docs/fr/concepts/webhooks) avec le secret `whsec_` de l'endpoint et renvoie l'événement analysé. Passez le corps exactement tel qu'il est arrivé :

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

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

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

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](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
