# 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.

```bash
npm install voozin
```

Requires Node.js 20 or later.

## Set up

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

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

```ts
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](https://voozin.com/docs/sending) (`reply_to`, `scheduled_at`, `template_id`).

## Templates

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

```ts
const { data: domains } = await voozin.domains.list(); // needs the domains:read scope
```

## Webhooks

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

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

```ts
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](https://voozin.com/docs/inbound/replying).

## Next.js helper

```ts
// 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](https://voozin.com/docs/guides/nextjs).

## Express helper

```ts
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](https://voozin.com/docs/guides/express).

## Errors

API errors throw `VoozinError` with `statusCode`, `error`, `message` and, for batch requests, `index`:

```ts
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](https://github.com/voozin/voozin-node).
