Sequences

Create, manage, and monitor automated email sequences with steps, delays, and conditions.

Sequences are automated drip campaigns that send a series of emails to contacts over time. Each sequence is defined as a YAML document with steps, delays, and conditions. Contacts are enrolled in sequences manually or via event-based triggers.

Create or update sequence

PUT /api/sequences/:id

Creates a new sequence or updates an existing one. This endpoint is idempotent.

Path parameters

Parameter	Type	Description
`id`	string	A unique identifier for the sequence (e.g. `onboarding`, `re-engagement`).

Request body

Field	Type	Required	Description
`id`	string	Yes	Must match the path parameter.
`name`	string	Yes	Human-readable name for the sequence.
`definition`	string	Yes	YAML definition of the sequence steps.
`triggers`	object[]	No	Event-based triggers that automatically enrol contacts.

Each trigger object:

Field	Type	Required	Description
`event`	string	Yes	Event name to listen for (e.g. `signed_up`).
`conditions`	object	No	Property conditions the contact must match.

Response

Returns the created or updated sequence.

{
  "id": "onboarding",
  "name": "Onboarding Sequence",
  "status": "draft",
  "definition": "steps:\n  - send: welcome-email\n  - delay: 1d\n  - send: getting-started\n",
  "triggers": [{ "event": "signed_up" }],
  "createdAt": "2025-09-10T08:00:00.000Z",
  "updatedAt": "2025-09-15T14:00:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing required fields or invalid YAML definition.

Examples

curl -X PUT https://api.kraiter.com/api/sequences/onboarding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "onboarding",
    "name": "Onboarding Sequence",
    "definition": "steps:\n  - send: welcome-email\n  - delay: 1d\n  - send: getting-started\n  - delay: 3d\n  - send: tips-and-tricks\n",
    "triggers": [{ "event": "signed_up" }]
  }'

const sequence = await kraiter.sequences.put("onboarding", {
  id: "onboarding",
  name: "Onboarding Sequence",
  definition: `steps:
  - send: welcome-email
  - delay: 1d
  - send: getting-started
  - delay: 3d
  - send: tips-and-tricks`,
  triggers: [{ event: "signed_up" }],
});

Partial update sequence

PATCH /api/sequences/:id

Updates the name or status of a sequence without replacing the full definition.

Path parameters

Parameter	Type	Description
`id`	string	The sequence ID.

Request body

Field	Type	Required	Description
`name`	string	No	New name for the sequence.
`status`	string	No	New status: `draft`, `active`, or `paused`.

Sequence statuses

Status	Description
`draft`	The sequence is not running. Contacts cannot be enrolled.
`active`	The sequence is live. Contacts can be enrolled and steps are executed.
`paused`	The sequence is paused. No new steps execute, but enrolled contacts remain.

Examples

curl -X PATCH https://api.kraiter.com/api/sequences/onboarding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

const sequence = await kraiter.sequences.update("onboarding", {
  status: "active",
});

List sequences

GET /api/sequences

Returns a paginated list of sequences.

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor.
`limit`	number	20	Number of sequences to return (max 100).
`status`	string	—	Filter by status: `draft`, `active`, or `paused`.

Examples

curl "https://api.kraiter.com/api/sequences?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

const sequences = await kraiter.sequences.list({ status: "active" });

Get sequence

GET /api/sequences/:id

Returns a single sequence including its full YAML definition and triggers.

Path parameters

Parameter	Type	Description
`id`	string	The sequence ID.

Errors

Code	Description
`NOT_FOUND`	No sequence with this ID exists.

Examples

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

const sequence = await kraiter.sequences.get("onboarding");

Delete sequence

DELETE /api/sequences/:id

Permanently deletes a sequence. Active enrolments are cancelled and pending steps are removed.

Response

Returns 204 No Content on success.

Errors

Code	Description
`NOT_FOUND`	No sequence with this ID exists.

Examples

curl -X DELETE https://api.kraiter.com/api/sequences/onboarding \
  -H "Authorization: Bearer YOUR_API_KEY"

await kraiter.sequences.delete("onboarding");

Get sequence run status

GET /api/sequences/:id/status

Returns aggregate run statistics for the sequence.

Response

{
  "sequenceId": "onboarding",
  "status": "active",
  "totalEnrolled": 1250,
  "activeEnrolments": 340,
  "completed": 870,
  "exited": 40
}

Examples

curl https://api.kraiter.com/api/sequences/onboarding/status \
  -H "Authorization: Bearer YOUR_API_KEY"

const status = await kraiter.sequences.getStatus("onboarding");

List enrolled contacts

GET /api/sequences/:id/contacts

Returns contacts currently enrolled in the sequence.

Examples

curl "https://api.kraiter.com/api/sequences/onboarding/contacts?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

const contacts = await kraiter.sequences.listContacts("onboarding");

List sends from sequence

GET /api/sequences/:id/sends

Returns all emails sent as part of this sequence.

Examples

curl "https://api.kraiter.com/api/sequences/onboarding/sends" \
  -H "Authorization: Bearer YOUR_API_KEY"

const sends = await kraiter.sequences.listSends("onboarding");

Dry-run sequence

POST /api/sequences/:id/dry-run

Simulates running the sequence for a specific contact without actually sending any emails. Use this to verify the sequence definition and preview which steps a contact would go through.

Request body

Field	Type	Required	Description
`contactId`	string	Yes	The contact to simulate the sequence for.

Response

{
  "steps": [
    { "action": "send", "templateId": "welcome-email", "scheduledFor": "2025-09-15T14:00:00.000Z" },
    { "action": "delay", "duration": "1d" },
    { "action": "send", "templateId": "getting-started", "scheduledFor": "2025-09-16T14:00:00.000Z" }
  ],
  "wouldComplete": true
}

Examples

curl -X POST https://api.kraiter.com/api/sequences/onboarding/dry-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cnt_01H8MZXK..." }'

const dryRun = await kraiter.sequences.dryRun("onboarding", {
  contactId: "cnt_01H8MZXK...",
});

Sequences

On this page