Libraries and pluginsView as Markdown

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 voozin

Requires 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 scope

Webhooks

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.