API Overview

The Kraiter API is a RESTful JSON API for managing contacts, templates, sequences, segments, campaigns, and transactional email. All endpoints are scoped to your organisation via JWT authentication.

Base URL

All API requests are made to:

https://api.kraiter.com

Every endpoint is prefixed with /api — for example, https://api.kraiter.com/api/contacts.

Authentication

Authenticate every request by including a Bearer token in the Authorization header. You can generate API keys from the Kraiter dashboard under Settings > API Keys.

curl https://api.kraiter.com/api/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

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

const kraiter = new Mailer({ apiKey: "YOUR_API_KEY" });

The API key determines your tenant (organisation) context. All resources returned are scoped to that tenant — you do not need to pass an organisation ID explicitly. See API Keys for details on key format, limits, and management.

Requests without a valid token receive a 401 Unauthorised response.

Request format

All request bodies must be JSON with the Content-Type: application/json header. Query parameters are used for filtering and pagination on GET endpoints.

Response format

Successful responses return a JSON object. Single-resource endpoints return the resource directly. List endpoints return an object with an items array and pagination metadata (nextCursor for cursor-paginated endpoints, or hasMore for the timeline and scheduled-send endpoints).

{
  "items": [{ "contactId": "cnt_01H...", "email": "alice@example.com" }],
  "nextCursor": "eyJpZCI6ImNudF8wMUgi..."
}

Errors

When a request fails, the API returns an error object with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "fields": { "email": ["Invalid email address"] } }
  }
}

The error object always includes a details object (empty {} when there is nothing to add). For 5xx responses in production, details is omitted (returned as {}) so internal error text is never leaked.

Common error codes

Pagination

List endpoints use cursor-based pagination. Pass cursor and limit as query parameters to page through results.

When there are more results, the response includes a nextCursor field. When there are no more results, nextCursor is null or absent.

# First page
curl "https://api.kraiter.com/api/contacts?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.kraiter.com/api/contacts?limit=10&cursor=eyJpZCI6ImNudF8wMUgi..." \
  -H "Authorization: Bearer YOUR_API_KEY"

// Iterate through all contacts
let cursor: string | undefined;
do {
  const page = await kraiter.contacts.list({ limit: 50, cursor });
  for (const contact of page.items) {
    console.log(contact.email);
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Rate limiting

The API allows 100 requests per minute per tenant. When you exceed this limit, requests return 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

The Retry-After response header contains the number of seconds to wait before making another request.

Best practices

• Cache responses where possible to reduce request volume.
• Use list endpoints with pagination rather than fetching resources individually.
• Implement exponential back-off when receiving 429 responses.
• Contact support if you consistently need higher limits.

Idempotency

PUT endpoints (templates, sequences) are idempotent — calling them with the same ID and body produces the same result. Use PUT to create or update resources without worrying about duplicate creation.

Resources

Explore the full reference for each resource:

• API Keys — Create and revoke API keys
• Contacts — Manage your audience
• Events — Track custom events
• Send — Transactional email
• Templates — Email templates with MJML
• Sequences — Automated drip sequences
• Segments — Dynamic audience groups
• Domains — Domain verification
• Campaigns — Organise sequences and templates
• Metrics — Engagement analytics
• Sends — Send history
• Scheduled — Scheduled sends
• Tenant — Tenant settings and sandbox whitelist