Koltrix Docs

Auth & meta

Resolve the tenant and permission set attached to the API key you're using.

GET/api/v2/me

Get current identity

Returns the tenant slug and permission set resolved from the Authorization header. Useful as a health-check from your integration to confirm the key is live and which workspace it points at.

Code sample

curl -X GET https://api.koltrix.com/api/v2/me \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "tenant": "acme",
  "permissions": [
    "read",
    "send",
    "contacts",
    "newsletter"
  ]
}

Lists

Newsletter audiences. Each list owns its own subscribers, double opt-in setting, and embed token.

GET/api/v2/lists

List newsletter lists

Returns every list visible to the current tenant.

Code sample

curl -X GET https://api.koltrix.com/api/v2/lists \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "id": "lst_4f3a",
      "name": "Product updates",
      "description": "Monthly changelog digest",
      "subscriber_count": 1284,
      "created_at": "2026-01-12T09:14:22Z"
    }
  ]
}

POST/api/v2/lists

Create a list

Provision a new newsletter list.

Parameters

Name	In	Type	Description
name*	body	string	Human-readable name shown in the dashboard.
description	body	string	Internal description, never shown to subscribers.

Code sample

curl -X POST https://api.koltrix.com/api/v2/lists \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product updates",
  "description": "Monthly changelog digest"
}'

Example response

{
  "id": "lst_4f3a",
  "name": "Product updates",
  "description": "Monthly changelog digest",
  "subscriber_count": 0,
  "created_at": "2026-05-26T10:11:12Z"
}

GET/api/v2/lists/:id

Get a list

Returns a single list by its id.

Parameters

Name	In	Type	Description
id*	path	string	The list id (e.g. `lst_4f3a`).

Code sample

curl -X GET https://api.koltrix.com/api/v2/lists/:id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "id": "lst_4f3a",
  "name": "Product updates",
  "description": "Monthly changelog digest",
  "subscriber_count": 1284,
  "created_at": "2026-01-12T09:14:22Z"
}

PATCH/api/v2/lists/:id

Update a list

Patch list metadata. Only supplied fields are changed.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
name	body	string	New display name.
description	body	string	New description.

Code sample

curl -X PATCH https://api.koltrix.com/api/v2/lists/:id \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Changelog"
}'

Example response

{
  "id": "lst_4f3a",
  "name": "Changelog",
  "description": "Monthly changelog digest",
  "subscriber_count": 1284
}

DELETE/api/v2/lists/:id

Delete a list

Permanently delete a list and all of its subscribers. This cannot be undone.

Parameters

Name	In	Type	Description
id*	path	string	The list id.

Code sample

curl -X DELETE https://api.koltrix.com/api/v2/lists/:id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "deleted": true,
  "id": "lst_4f3a"
}

Subscribers

Add, import, list, and unsubscribe subscribers on a given list. Unsubscribes hit the global suppression list automatically.

GET/api/v2/lists/:id/subscribers

List subscribers

Paginated subscribers for a list.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
limit	query	number	Page size (default 50, max 200).
offset	query	number	Offset into the result set.

Code sample

curl -X GET https://api.koltrix.com/api/v2/lists/:id/subscribers \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "id": "sub_91ac",
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "status": "subscribed",
      "created_at": "2026-04-02T14:01:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST/api/v2/lists/:id/subscribers

Add a subscriber

Add a single subscriber to a list. Duplicate emails return the existing row instead of erroring.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
email*	body	string	Subscriber email (will be lower-cased).
first_name	body	string	First name for merge tags.
last_name	body	string	Last name for merge tags.
metadata	body	object	Arbitrary JSON key/value pairs.

Code sample

curl -X POST https://api.koltrix.com/api/v2/lists/:id/subscribers \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "metadata": {
    "plan": "pro",
    "source": "landing-hero"
  }
}'

Example response

{
  "id": "sub_91ac",
  "email": "[email protected]",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "status": "subscribed",
  "created_at": "2026-05-26T10:14:33Z"
}

POST/api/v2/lists/:id/subscribers/import

Bulk import subscribers

Import up to 10k subscribers in a single call. The request is processed asynchronously and returns a job id you can poll.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
subscribers*	body	array	Array of subscriber objects (same shape as POST /subscribers).

Code sample

curl -X POST https://api.koltrix.com/api/v2/lists/:id/subscribers/import \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "subscribers": [
    {
      "email": "[email protected]",
      "first_name": "One"
    },
    {
      "email": "[email protected]",
      "first_name": "Two"
    }
  ]
}'

Example response

{
  "job_id": "job_imp_77fe",
  "accepted": 2,
  "rejected": 0,
  "status": "queued"
}

DELETE/api/v2/lists/:id/subscribers/:sub_id

Delete a subscriber

Hard-delete a subscriber row. To unsubscribe without losing history, use the unsubscribe endpoint instead.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
sub_id*	path	string	The subscriber id.

Code sample

curl -X DELETE https://api.koltrix.com/api/v2/lists/:id/subscribers/:sub_id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "deleted": true,
  "id": "sub_91ac"
}

POST/api/v2/lists/:id/subscribers/:sub_id/unsubscribe

Unsubscribe

Marks the subscriber as `unsubscribed` and adds their email to the tenant-wide suppression list.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
sub_id*	path	string	The subscriber id.

Code sample

curl -X POST https://api.koltrix.com/api/v2/lists/:id/subscribers/:sub_id/unsubscribe \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "id": "sub_91ac",
  "status": "unsubscribed",
  "unsubscribed_at": "2026-05-26T10:18:02Z"
}

Broadcasts

One-off campaigns sent to every subscribed member of a list. For drip series see Sequences.

POST/api/v2/lists/:id/broadcast

Send a broadcast

Queue a broadcast to every subscribed member of the list. Returns immediately with a `broadcast_id` — delivery happens in the worker.

Parameters

Name	In	Type	Description
id*	path	string	The list id.
subject*	body	string	Email subject line.
body_html*	body	string	HTML body. Merge tags like `{{first_name}}` are interpolated per recipient.
body_text	body	string	Plain-text fallback. Auto-generated if omitted.
from*	body	string	From address. Must be on a verified domain.

Code sample

curl -X POST https://api.koltrix.com/api/v2/lists/:id/broadcast \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "[email protected]",
  "subject": "What shipped in May",
  "body_html": "<h1>Hi {{first_name}},</h1><p>This month we shipped…</p>",
  "body_text": "Hi {{first_name}}, this month we shipped…"
}'

Example response

{
  "broadcast_id": "brd_aa12",
  "status": "queued",
  "recipients": 1284,
  "enqueued_at": "2026-05-26T10:20:01Z"
}

Sequences

Drip automations. A sequence has an entry trigger (e.g. `subscribed`) and an ordered list of steps that send after a configurable delay.

GET/api/v2/sequences

List sequences

Returns all sequences for the current tenant.

Code sample

curl -X GET https://api.koltrix.com/api/v2/sequences \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "id": "seq_2c81",
      "name": "Welcome series",
      "list_id": "lst_4f3a",
      "trigger": "subscribed",
      "step_count": 3,
      "created_at": "2026-03-01T00:00:00Z"
    }
  ],
  "total": 1
}

POST/api/v2/sequences

Create a sequence

Create an empty sequence; add steps with POST `/steps`.

Parameters

Name	In	Type	Description
name*	body	string	Sequence name.
list_id*	body	string	The list whose subscribers feed this sequence.
trigger*	body	string	Entry trigger. Currently supported: `subscribed`, `manual`.

Code sample

curl -X POST https://api.koltrix.com/api/v2/sequences \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Welcome series",
  "list_id": "lst_4f3a",
  "trigger": "subscribed"
}'

Example response

{
  "id": "seq_2c81",
  "name": "Welcome series",
  "list_id": "lst_4f3a",
  "trigger": "subscribed",
  "step_count": 0,
  "created_at": "2026-05-26T10:22:14Z"
}

DELETE/api/v2/sequences/:id

Delete a sequence

Delete a sequence and stop any in-flight enrolments. Already-delivered messages are unaffected.

Parameters

Name	In	Type	Description
id*	path	string	The sequence id.

Code sample

curl -X DELETE https://api.koltrix.com/api/v2/sequences/:id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "deleted": true,
  "id": "seq_2c81"
}

GET/api/v2/sequences/:id/steps

List sequence steps

Returns the ordered steps for a sequence.

Parameters

Name	In	Type	Description
id*	path	string	The sequence id.

Code sample

curl -X GET https://api.koltrix.com/api/v2/sequences/:id/steps \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "id": "stp_001",
      "sequence_id": "seq_2c81",
      "position": 1,
      "delay_minutes": 0,
      "subject": "Welcome",
      "body_html": "<p>Glad you're here.</p>"
    },
    {
      "id": "stp_002",
      "sequence_id": "seq_2c81",
      "position": 2,
      "delay_minutes": 2880,
      "subject": "Day 2 — getting set up",
      "body_html": "<p>Here's how to send your first email…</p>"
    }
  ],
  "total": 2
}

POST/api/v2/sequences/:id/steps

Add a sequence step

Append a step to the end of the sequence. `delay_minutes` is the wait between the previous step (or trigger, for step 1) and this one.

Parameters

Name	In	Type	Description
id*	path	string	The sequence id.
subject*	body	string	Step email subject.
body_html*	body	string	Step email body.
body_text	body	string	Plain-text fallback.
delay_minutes*	body	number	Minutes to wait before sending this step.
from	body	string	Override From address for this step.

Code sample

curl -X POST https://api.koltrix.com/api/v2/sequences/:id/steps \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Welcome to Koltrix",
  "body_html": "<p>Hi {{first_name}}, glad you're here.</p>",
  "delay_minutes": 0
}'

Example response

{
  "id": "stp_003",
  "sequence_id": "seq_2c81",
  "position": 3,
  "delay_minutes": 0,
  "subject": "Welcome to Koltrix"
}

DELETE/api/v2/sequences/:id/steps/:step_id

Delete a sequence step

Remove a step from the sequence. Remaining steps' positions shift up.

Parameters

Name	In	Type	Description
id*	path	string	The sequence id.
step_id*	path	string	The step id.

Code sample

curl -X DELETE https://api.koltrix.com/api/v2/sequences/:id/steps/:step_id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "deleted": true,
  "id": "stp_002"
}

Transactional emails

One-shot transactional sends. Pass an `Idempotency-Key` header to safely retry on network failures.

POST/api/v2/emails

Send a transactional email

Queue a transactional email for delivery. Returns a `message_id` you can use against `/messages/:id` and `/messages/:id/events`. Idempotency keys dedupe duplicate sends for 24 hours.

Parameters

Name	In	Type	Description
from*	body	string	From address. Must be on a verified domain.
to*	body	array	Array of recipient addresses (max 50).
subject*	body	string	Subject line.
body_html*	body	string	HTML body.
body_text	body	string	Plain-text fallback. Auto-generated from HTML if omitted.
reply_to	body	string	Reply-To address.
cc	body	array	Array of CC addresses.
bcc	body	array	Array of BCC addresses.
attachments	body	array	Array of `{ filename, content_type, content }` where `content` is base64-encoded.
headers	body	object	Custom RFC-5322 headers as a flat key/value map.
Idempotency-Key	header	string	Auto-generated per Run click. Pass the same value on retry to dedupe.

Code sample

curl -X POST https://api.koltrix.com/api/v2/emails \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "subject": "Your invoice is ready",
  "body_html": "<p>Thanks for your order.</p>",
  "body_text": "Thanks for your order."
}'

Example response

{
  "id": "msg_018f5c12",
  "status": "queued",
  "to": [
    "[email protected]"
  ],
  "subject": "Your invoice is ready",
  "enqueued_at": "2026-05-26T10:25:11Z"
}

Messages

Inspect every outbound message — transactional, broadcast, or sequence — and its delivery timeline.

GET/api/v2/messages

List messages

Paginated outbound messages. Filter by status (queued/sent/delivered/bounced/complained) and recipient.

Parameters

Name	In	Type	Description
status	query	string	One of `queued`, `sent`, `delivered`, `bounced`, `complained`, `failed`.
to	query	string	Filter by recipient address (exact match).
limit	query	number	Page size (default 50, max 200).
offset	query	number	Offset into the result set.

Code sample

curl -X GET https://api.koltrix.com/api/v2/messages \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "id": "msg_018f5c12",
      "from": "[email protected]",
      "to": [
        "[email protected]"
      ],
      "subject": "Your invoice is ready",
      "status": "delivered",
      "created_at": "2026-05-26T10:25:11Z",
      "delivered_at": "2026-05-26T10:25:14Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/api/v2/messages/:id

Get a message

Returns a single outbound message by id.

Parameters

Name	In	Type	Description
id*	path	string	The message id.

Code sample

curl -X GET https://api.koltrix.com/api/v2/messages/:id \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "id": "msg_018f5c12",
  "from": "[email protected]",
  "to": [
    "[email protected]"
  ],
  "subject": "Your invoice is ready",
  "status": "delivered",
  "opens": 1,
  "clicks": 0,
  "created_at": "2026-05-26T10:25:11Z",
  "delivered_at": "2026-05-26T10:25:14Z"
}

GET/api/v2/messages/:id/events

Get message events

Returns the full timeline for a message — accept, deferral, delivery, open and click events.

Parameters

Name	In	Type	Description
id*	path	string	The message id.

Code sample

curl -X GET https://api.koltrix.com/api/v2/messages/:id/events \
  -H "Authorization: Bearer kx_live_..."

Example response

{
  "data": [
    {
      "type": "queued",
      "at": "2026-05-26T10:25:11Z"
    },
    {
      "type": "sent",
      "at": "2026-05-26T10:25:12Z"
    },
    {
      "type": "delivered",
      "at": "2026-05-26T10:25:14Z",
      "smtp_code": 250
    },
    {
      "type": "opened",
      "at": "2026-05-26T10:30:02Z",
      "ua": "Apple Mail"
    }
  ],
  "total": 4
}