---
title: Node.js-SDK
description: "E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit @billionsend/node: jede API-Operation, Wiederholungsversuche und Idempotenzschlüssel."
ai:
  exclude: true
---

Das Paket `@billionsend/node` ist der BillionSend-Client für Node.js und TypeScript. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Seine Typen stammen aus dem OpenAPI-Dokument der API. Der Quellcode liegt auf GitHub unter [billionsend/billionsend-node](https://github.com/billionsend/billionsend-node).

## Installation

Erfordert Node 18 oder neuer. Das Paket hat keine Abhängigkeiten und enthält sowohl ES-Module als auch CommonJS.

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

## E-Mail senden

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // liest 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_...")` nimmt den Schlüssel direkt entgegen. Mit `new BillionSend({ apiKey, baseUrl, timeoutMs, maxRetries, fetch })` legen Sie den Rest fest. `BILLIONSEND_BASE_URL` überschreibt die API-URL.

## Idempotenz und Wiederholungsversuche

Die Versand-Methoden (`emails.send`, `emails.batch`, Antworten und Weiterleitungen, `inboxes.send`, `inboxes.drafts.send`) senden immer einen `Idempotency-Key`. Ohne Ihren eigenen `idempotencyKey` erhält jeder Aufruf einen neuen zufälligen Schlüssel, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.

Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt (`maxRetries`): 429, 5xx, Timeouts, Netzwerkfehler und das `409 concurrent_idempotent_requests`, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: Lesezugriffe, `PUT` und `DELETE` sowie die Versand-Methoden. Der Client wartet so lange, wie `retry-after` es verlangt, bis zu einer Minute, und weicht sonst exponentiell zurück.

## Fehler

Methoden werfen nie eine Ausnahme. Jede liefert `{ data, error, headers }`, wobei genau eines von `data` und `error` gesetzt ist. `error` ist ein `BillionSendError` in einer Klasse für seine Art: `ValidationError` (400, 422), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, mit `retryAfter` in Sekunden), `APIError` (5xx), `APIConnectionError` und `APITimeoutError` (keine Antwort). Jeder trägt `statusCode`, `name` (den Fehlernamen der API), `message` und `requestId`, den `x-request-id` der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.

```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` und die Ereignis-Streams werfen dieselben Fehler, da sie nicht pro Eintrag einen zurückgeben können.

## Das Postfach eines Agenten

Warten Sie im [Ereignis-Stream](/docs/de/inboxes) auf neue Mails, lesen Sie sie und antworten Sie in ihrem Thread:

```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; // Ereignisse können fehlen: Threads erneut lesen
  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}` },
  );
}
```

Der Stream verbindet sich mit `Last-Event-ID` neu, wenn die Verbindung abbricht, und spielt Verpasstes nach, sodass kein Ereignis verloren geht. Behalten Sie `opened.data.lastEventId`, um in einem späteren Durchlauf mit `{ lastEventId }` fortzusetzen. Ein `stream.gap` kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. `bs.inboxes.events.stream()` folgt jedem Postfach des Teams.

## Webhooks verifizieren

`verifyWebhook` prüft Signatur und Zeitstempel einer [Webhook](/docs/de/concepts/webhooks)-Zustellung mit dem `whsec_`-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist:

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

Mit Express lesen Sie den Body mit `express.raw({ type: "application/json" })` und übergeben `req.body` und `req.headers`. Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt (`tolerance` ändert das), und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.

## Agent-Registrierung

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

Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter [Agent-Registrierung](/docs/de/agent-signup).
