SDK Overview

The @kraiter/sdk package gives you a typed, Promise-based interface to every Kraiter API resource. It handles authentication, pagination, and error handling so you can focus on your integration logic.

Installation

npm install @kraiter/sdk

Or with your preferred package manager:

pnpm add @kraiter/sdk
yarn add @kraiter/sdk

Initialisation

Create a client instance by passing your API key. Generate one from Settings in the dashboard.

import { Mailer } from '@kraiter/sdk';

const kraiter = new Mailer({
  apiKey: process.env.KRAITER_API_KEY,
});

The exported client class is named Mailer. You can bind it to whatever variable name you like — the examples throughout this reference use kraiter.

Configuration options

* Either apiKey or getToken must be provided.

Authentication

The SDK uses bearer-token authentication. When you provide an apiKey, it is sent as a Bearer token with every request. No token refresh logic is needed — API keys do not expire (but can be revoked from the dashboard).

const kraiter = new Mailer({
  apiKey: process.env.KRAITER_API_KEY,
});

Error handling

All SDK methods throw a MailerError when the API returns a non-2xx response. The error includes structured information about what went wrong. The SDK does not retry failed requests — retries, if any, are your responsibility.

import { MailerError } from '@kraiter/sdk';

try {
  await kraiter.contacts.get('non-existent-id');
} catch (error) {
  if (error instanceof MailerError) {
    console.error(error.code);       // e.g. "NOT_FOUND"
    console.error(error.message);    // e.g. "Contact not found"
    console.error(error.statusCode); // e.g. 404
    console.error(error.details);    // structured details, e.g. per-field validation errors
  }
}

MailerError properties

Requests that exceed the configured timeout reject with a MailerTimeoutError instead — this is a separate class (not a subclass of MailerError), so check for it explicitly if you need to distinguish timeouts.

import { MailerTimeoutError } from '@kraiter/sdk';

try {
  await kraiter.contacts.list();
} catch (error) {
  if (error instanceof MailerTimeoutError) {
    console.error('Request timed out');
  }
}

Common error codes

Pagination

Methods that return collections resolve to a single page shaped as { items, nextCursor }. The SDK does no hidden fetching: pass limit to control page size, and feed nextCursor back in as cursor to fetch the next page. When nextCursor is undefined, you have reached the end.

// Fetch a single page of up to 50 contacts
const page = await kraiter.contacts.list({ limit: 50 });

for (const contact of page.items) {
  console.log(contact.email);
}

To walk every page, loop until nextCursor is undefined:

let cursor: string | undefined;

do {
  const page = await kraiter.contacts.list({ cursor, limit: 50 });
  for (const contact of page.items) {
    console.log(contact.email);
  }
  cursor = page.nextCursor;
} while (cursor);

To stop early, simply break out of your loop and stop requesting further pages.

Resource namespaces

The SDK organises methods under resource namespaces on the client instance: