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 Kraiter from "@kraiter/sdk";

const kraiter = new Kraiter({ 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 a data array and pagination metadata.

{
  "data": [{ "id": "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": "The 'email' field is required."
  }
}

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.data) {
    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