Sequences

The kraiter.sequences namespace provides methods for building and managing automated email sequences. A sequence is a series of steps — emails, delays, and conditions — that contacts progress through automatically.

create

Creates a new sequence.

const sequence = await kraiter.sequences.create({
  id: 'seq_onboarding',
  name: 'Onboarding Drip',
  definition: JSON.stringify({
    steps: [
      { type: 'email', templateId: 'tmpl_welcome', delay: '0d' },
      { type: 'delay', duration: '2d' },
      { type: 'email', templateId: 'tmpl_getting_started', delay: '0d' },
    ],
  }),
  triggers: [
    { type: 'event', eventName: 'signed_up' },
  ],
});

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	A unique identifier for the sequence.
`name`	`string`	Yes	A human-readable name.
`definition`	`string`	Yes	A JSON string describing the sequence steps.
`triggers`	`Trigger[]`	No	An array of trigger objects that enrol contacts into the sequence automatically.

Returns

Promise<Sequence> — the newly created sequence object.

Errors

Code	When
`CONFLICT`	A sequence with this ID already exists.
`VALIDATION_ERROR`	The definition JSON is invalid or a referenced template does not exist.

get

Retrieves a sequence by ID.

const sequence = await kraiter.sequences.get('seq_onboarding');
console.log(sequence.name, sequence.status);

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID.

Returns

Promise<Sequence> — the sequence object.

Errors

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

list

Lists sequences with optional filtering. Returns an async iterator.

for await (const sequence of kraiter.sequences.list()) {
  console.log(sequence.id, sequence.name, sequence.status);
}

Filter by status:

for await (const sequence of kraiter.sequences.list({ status: 'active' })) {
  console.log(sequence.name);
}

Parameters

Parameter	Type	Required	Description
`cursor`	`string`	No	Pagination cursor.
`limit`	`number`	No	Maximum items per page.
`status`	`string`	No	Filter by sequence status (e.g. `"active"`, `"paused"`, `"draft"`).

Returns

AsyncIterable<Sequence> — an async iterator of sequence objects.

update

Updates an existing sequence. Only the fields you include are changed.

const updated = await kraiter.sequences.update('seq_onboarding', {
  name: 'Onboarding Drip v2',
});

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID to update.
`name`	`string`	No	Updated name.
`definition`	`string`	No	Updated step definition as a JSON string.
`triggers`	`Trigger[]`	No	Updated triggers.

Returns

Promise<Sequence> — the updated sequence object.

Errors

Code	When
`NOT_FOUND`	No sequence exists with this ID.
`VALIDATION_ERROR`	The updated definition is invalid.

delete

Permanently deletes a sequence. Active enrolments are cancelled.

await kraiter.sequences.delete('seq_onboarding');

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID to delete.

Returns

Promise<void>

Errors

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

getStatus

Returns the current status and enrolment statistics for a sequence.

const status = await kraiter.sequences.getStatus('seq_onboarding');
console.log(status.status);           // "active"
console.log(status.totalEnrolled);     // 1250
console.log(status.activeEnrolments);  // 340
console.log(status.completedCount);    // 910

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID.

Returns

Promise<SequenceStatus> — status and statistics for the sequence.

Errors

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

dryRun

Simulates running a contact through the sequence without actually sending any emails. Returns the steps the contact would pass through, useful for debugging sequence logic.

const result = await kraiter.sequences.dryRun('seq_onboarding', 'con_abc123');

for (const step of result.steps) {
  console.log(step.type, step.templateId, step.wouldSend);
}

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID.
`contactId`	`string`	Yes	The contact ID to simulate.

Returns

Promise<DryRunResult> — the simulated sequence path for the contact.

Errors

Code	When
`NOT_FOUND`	The sequence or contact does not exist.

getContacts

Lists the contacts currently enrolled in a sequence. Returns an async iterator.

for await (const contact of kraiter.sequences.getContacts('seq_onboarding')) {
  console.log(contact.email, contact.id);
}

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID.
`cursor`	`string`	No	Pagination cursor.
`limit`	`number`	No	Maximum items per page.

Returns

AsyncIterable<Contact> — an async iterator of enrolled contact objects.

getSends

Lists all sends generated by a sequence. Returns an async iterator.

for await (const send of kraiter.sequences.getSends('seq_onboarding')) {
  console.log(send.contactId, send.templateId, send.status);
}

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The sequence ID.
`cursor`	`string`	No	Pagination cursor.
`limit`	`number`	No	Maximum items per page.

Returns

AsyncIterable<Send> — an async iterator of send records.

Sequences

On this page