zerokit-sdk

Official TypeScript / JavaScript SDK for the Zerokit transactional email API.

Zero runtime dependencies. Works in Node 18+, Bun, Deno, Cloudflare Workers, and modern browsers — anywhere the global fetch is available.

Install

npm install zerokit-sdk
# or
pnpm add zerokit-sdk
# or
bun add zerokit-sdk

Quick start

import { Zerokit } from "zerokit-sdk";

const zerokit = new Zerokit({
  apiKey: process.env.ZEROKIT_API_KEY!,
});

const { id } = await zerokit.sendEmail({
  from: "Acme <[email protected]>",
  to: ["[email protected]"],
  subject: "Welcome to Acme",
  html: "<p>Hello Jane</p>",
  text: "Hello Jane",
});

console.log("Queued:", id);

Get an API key from your Zerokit dashboard. Use zk_test_* keys in development and zk_live_* in production.

Methods

sendEmail(input)

Queue a transactional email for delivery. Returns immediately with { id, status: "queued" } — SES handoff happens in the background. Subscribe to a webhook to learn about delivery, bounces, opens, and clicks.

await zerokit.sendEmail({
  from: "Acme <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  subject: "Hello",
  html: "<p>Hi</p>",
  text: "Hi",
});

listEmails()

Return every email in the workspace, newest-first.

const emails = await zerokit.listEmails();
for (const email of emails) {
  console.log(email.id, email.status, email.subject);
}

getEmail(id)

Fetch a single email by ID. Throws ZerokitError with status 404 if missing.

const email = await zerokit.getEmail("email_2bV4dXyZ8AfQpkw7Lp");
console.log(email.status, email.providerMessageId);

Error handling

Every non-2xx response throws a ZerokitError. The error carries the HTTP status and the raw response body so you can branch on specific failure modes:

import { Zerokit, ZerokitError } from "zerokit-sdk";

try {
  await zerokit.sendEmail({
    /* ... */
  });
} catch (err) {
  if (err instanceof ZerokitError) {
    if (err.status === 401) {
      // Bad API key — re-issue from the dashboard.
    } else if (err.status === 400) {
      // Domain not verified, or body validation failed.
      console.error(err.payload);
    } else if (err.status === 429) {
      // Plan cap hit. Read err.payload.error for the limit + plan name.
    }
  }
  throw err;
}

Configuration

new Zerokit({
  apiKey: "zk_live_...",
  // Optional — override for self-hosted or local dev.
  baseUrl: "https://api.zerokit.co",
  // Optional — inject a custom fetch (testing, instrumentation, retry).
  fetch: globalThis.fetch,
});

Cloudflare Workers

The SDK uses the global fetch so it drops into a Worker without any Node polyfills:

import { Zerokit } from "zerokit-sdk";

export default {
  async fetch(req: Request, env: { ZEROKIT_API_KEY: string }) {
    const zerokit = new Zerokit({ apiKey: env.ZEROKIT_API_KEY });
    await zerokit.sendEmail({
      from: "Acme <[email protected]>",
      to: ["[email protected]"],
      subject: "Hello",
      html: "<p>Hello</p>",
    });
    return new Response("ok");
  },
};

Links

• Documentation: zerokit.co/docs
• API Reference: zerokit.co/docs/api-reference
• Dashboard: zerokit.co/app
• Source: github.com/zerokit-co/zerokit

License

MIT — see LICENSE.