Node.js-SDK
E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit @billionsend/node: jede API-Operation, Wiederholungsversuche und Idempotenzschlüssel.
Das Paket @billionsend/node ist der BillionSend-Client für Node.js und TypeScript. Es deckt jede Operation der API-Referenz 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.
Installation
Erfordert Node 18 oder neuer. Das Paket hat keine Abhängigkeiten und enthält sowohl ES-Module als auch CommonJS.
npm install @billionsend/node
E-Mail senden
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.
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 auf neue Mails, lesen Sie sie und antworten Sie in ihrem Thread:
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-Zustellung mit dem whsec_-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist:
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
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.