Sequences

A sequence is a series of emails sent to each new subscriber of a list, on a schedule that starts when they join: a welcome email straight away, a setup guide a day later, a check-in three days after that. Koltrix schedules every step for every subscriber; you don't run a cron job.

Every endpoint is in the API reference. Reading needs read or newsletter; changes need newsletter.

Create a sequence#

curl https://api.koltrix.com/api/v2/sequences \
  -H "Authorization: Bearer $KOLTRIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome series", "list_id": "0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d" }'

{
  "id": "3a2b1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
  "list_id": "0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d",
  "name": "Welcome series",
  "trigger": "subscribe",
  "active": true,
  "step_count": 0,
  "created_at": "2026-10-02T12:00:00Z",
  "updated_at": "2026-10-02T12:00:00Z"
}

trigger is subscribe, the only trigger: a person is enrolled when they become an active subscriber of the list. New sequences are active.

Add steps#

Each step has a position (starting at 0), a delay_hours counted from the previous step (from enrolment for step 0), a subject and a body.

curl https://api.koltrix.com/api/v2/sequences/$SEQ_ID/steps \
  -H "Authorization: Bearer $KOLTRIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 0,
    "delay_hours": 0,
    "subject": "Welcome to Acme",
    "body_html": "<p>Hi {{first_name|there}}, glad you are here.</p>"
  }'
 
curl https://api.koltrix.com/api/v2/sequences/$SEQ_ID/steps \
  -H "Authorization: Bearer $KOLTRIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 1,
    "delay_hours": 24,
    "subject": "Your five-minute setup",
    "body_html": "<p>Here is the setup guide we promised.</p>"
  }'
 
curl https://api.koltrix.com/api/v2/sequences/$SEQ_ID/steps \
  -H "Authorization: Bearer $KOLTRIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 2,
    "delay_hours": 72,
    "subject": "How is it going?",
    "body_html": "<p>Anything I can help with? Just reply.</p>"
  }'

Each delay counts from the step before it, so this sends at 0 hours, 24 hours and 96 hours after someone joins.

In step bodies, {{email}} and {{unsubscribe_url}} are filled in. The name variables are always empty in sequences, so give {{first_name}} a fallback, as above. The subject is sent as written.

Inspect and delete#

Deletes answer 204. Steps can't be edited: delete one and add a new one in its place.

How a subscriber moves through it#

When someone becomes an active subscriber, by POST /api/v2/lists/:id/subscribers or by confirming a double opt-in, Koltrix enrols them in every active sequence on the list and schedules step 0. After each step it schedules the next, until the last.

Before each step Koltrix checks:

1. Still subscribed? Someone who unsubscribed is skipped, and their enrolment ends.
2. On the suppression list? Then nothing is sent and the enrolment ends.
3. Does the list have a From address? If not, the enrolment is paused until you set from_address on the list.
4. Within today's sending cap for a new domain? If not, the step waits until tomorrow.

Each step goes out with an unsubscribe link and a List-Unsubscribe header. Unsubscribing at any point stops the rest of the sequence.

Subscribers added by CSV import aren't enrolled, and nor are people who were already on the list when you created the sequence.

Limits#

Delays are whole hours. For "send in 30 seconds", use POST /api/v2/emails.