Node.js SDK
The official voozin package for Node.js, Bun, Deno and edge runtimes. It is written in TypeScript, has no dependencies, and uses the platform's fetch and Web Crypto.
npm install voozinRequires Node.js 20 or later.
Set up
import { Voozin } from "voozin";
const voozin = new Voozin(process.env.VOOZIN_API_KEY);If you leave out the key, the client reads VOOZIN_API_KEY from the environment. Options:
new Voozin(apiKey, {
baseUrl: "https://api.voozin.com", // default
maxRetries: 2, // retries for 429 and 5xx responses and network errors
timeout: 30_000, // milliseconds per request
});Emails
const { id } = await voozin.emails.send(
{ from: "Acme <hello@acme.com>", to: ["ada@example.com"], subject: "Hi", html: "<p>Hello</p>" },
{ idempotencyKey: "welcome-user-42" },
);
await voozin.emails.batch([{ … }, { … }], { idempotencyKey: "digest-2026-10-26" });
const email = await voozin.emails.get(id);
const page = await voozin.emails.list({ tag: "category:receipt", limit: 50 });
// page.data, page.next_cursor
await voozin.emails.reschedule(id, "2026-11-02T09:00:00Z");
await voozin.emails.cancel(id);Parameters use the same snake_case names as the REST API (reply_to, scheduled_at, template_id).
Templates
const { data } = await voozin.templates.list();
const template = await voozin.templates.get("password-reset");
const preview = await voozin.templates.render({ subject: "Hi {{ name }}", html: "<p>Hi {{ name }}</p>", variables: { name: "Ada" } });Domains
const { data: domains } = await voozin.domains.list(); // needs the domains:read scopeWebhooks
import { verifyWebhook, WebhookVerificationError } from "voozin";
try {
const event = await verifyWebhook(rawBody, headers, process.env.VOOZIN_WEBHOOK_SECRET!);
// event.type, event.timestamp, event.data
} catch (err) {
if (err instanceof WebhookVerificationError) {
// respond 400
}
}rawBody must be the exact request body as a string or bytes. headers can be a Headers object or a plain object. Signatures older than five minutes are rejected. voozin.webhooks.verify(...) does the same.
Manage endpoints with voozin.webhooks.create({ url, events }) (the response includes the secret), list(), get(id), update(id, …) and delete(id).
The returned event is typed, so event.type === "inbound.received" narrows event.data to an inbound message.
Inbound
const route = await voozin.inbound.routes.create({ domain_id, pattern: "support", endpoint_id });
const { data: routes } = await voozin.inbound.routes.list();
await voozin.inbound.routes.delete(route.id);
const message = await voozin.inbound.get(inboundId);
const raw = await voozin.inbound.raw(inboundId); // ArrayBuffer
const attachment = await voozin.inbound.attachment(inboundId, 0); // { filename, contentType, content: ArrayBuffer }
await voozin.inbound.replay(inboundId);Reply to an inbound message
await voozin.inbound.reply(
event.data,
{ from: "Acme Support <support@acme.com>", text: "Thanks, we're on it." },
{ idempotencyKey: `reply-${event.data.id}` },
);reply sends to the message's reply_to (or from) address, sets Re: on the subject, and sets In-Reply-To and References so the reply threads. See Replying to inbound mail.
Next.js helper
// app/api/webhooks/voozin/route.ts
import { createWebhookHandler } from "voozin/next";
export const POST = createWebhookHandler({
secret: process.env.VOOZIN_WEBHOOK_SECRET!,
async onEvent(event) {
if (event.type === "email.bounced") await markBounced(event.data.recipient);
},
});The handler reads the raw body, verifies it, calls onEvent, and responds 204 (or 400 for a bad signature). See the Next.js guide.
Express helper
import express from "express";
import { webhookHandler } from "voozin/express";
const app = express();
app.post(
"/webhooks/voozin",
express.raw({ type: "application/json" }),
webhookHandler({ secret: process.env.VOOZIN_WEBHOOK_SECRET!, onEvent: async (event) => { /* … */ } }),
);Mount it with express.raw (or before any JSON body parser) so the signature can be checked against the raw body. See the Express guide.
Errors
API errors throw VoozinError with statusCode, error, message and, for batch requests, index:
import { VoozinError } from "voozin";
try {
await voozin.emails.send(params);
} catch (err) {
if (err instanceof VoozinError && err.statusCode === 402) {
// the plan doesn't include transactional email, or billing lapsed
}
throw err;
}429 and 5xx responses and network errors are retried with backoff (respecting Retry-After) up to maxRetries times. Requests with an idempotencyKey are always safe to retry.
Source
The package is open source (MIT): github.com/voozin/voozin-node.