Getting started

SDKs

The API is plain JSON over HTTPS, so any language works. The official SDK adds types, typed errors and retries.

TypeScript

@sendbaze/sdk is a zero-dependency client built on fetch. It runs on Node.js 20+, Bun, Deno, Cloudflare Workers and Vercel Edge. The package ships ESM and CommonJS builds with full type definitions.

terminal

npm install @sendbaze/sdk
# or
pnpm add @sendbaze/sdk

Sending and handling errors

send.ts

import { Sendbaze, SendbazeError } from "@sendbaze/sdk";

const sendbaze = new Sendbaze({ apiKey: process.env.SENDBAZE_API_KEY! });

try {
  const { id } = await sendbaze.emails.send(
    {
      from: "Yourshop <orders@yourshop.co.za>",
      to: ["thandi@example.com"],
      subject: "Your order #1042 has shipped",
      html: "<p>Tracking: <b>CG123456789ZA</b></p>",
      tags: ["order-shipped"],
    },
    { idempotencyKey: "order-1042-shipped" },
  );
  console.log(id); // em_01j9...
} catch (error) {
  if (error instanceof SendbazeError) {
    // error.code is stable: "validation_error", "rate_limited", ...
    console.error(error.code, error.fields, error.requestId);
  } else {
    throw error;
  }
}

Every non-2xx response throws a SendbazeError whose code matches the errors reference. Network failures and timeouts throw SendbazeConnectionError instead, so you can retry them safely with the same idempotency key.

Batches

batch.ts

const { results } = await sendbaze.sms.batch([
  { to: "+27821234567", body: "Your table is ready.", class: "transactional" },
  { to: "+27831234567", body: "Your table is ready.", class: "transactional" },
]);

for (const result of results) {
  if (result.ok) console.log(result.data.id, result.data.credits);
  else console.warn(result.index, result.error.code);
}

Looking up a message

status.ts

const message = await sendbaze.emails.get("em_01j9...");
console.log(message.status); // "queued" | "sent" | "delivered" | "bounced" | ...
for (const event of message.events) console.log(event.type, event.occurredAt);

Client options

apiKey: a live or test key. Required.
baseUrl: defaults to the production API. Point it at a mock server in tests.
timeoutMs: request timeout, default 30 seconds.
fetch: a custom fetch implementation, for older runtimes or for tests.

Other languages

A Python package and an n8n community node are next on the roadmap, after the TypeScript SDK reaches 1.0. Until then the API reference has cURL examples for every endpoint, and the OpenAPI specification will be published with the public launch.