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.

upsert

Creates a sequence, or replaces it if one already exists with the given ID. The sequence ID is passed as the first argument; the body is passed as the second.

const sequence = await kraiter.sequences.upsert('seq_onboarding', {
  name: 'Onboarding Drip',
  content: JSON.stringify({
    steps: [
      { type: 'email', templateId: 'tmpl_welcome', delay: '0d' },
      { type: 'delay', duration: '2d' },
      { type: 'email', templateId: 'tmpl_getting_started', delay: '0d' },
    ],
  }),
  enabled: true,
});

Parameters

Returns

Promise<Sequence> — the created or replaced sequence object.

Errors

get

Retrieves a sequence by ID. Returns null if not found. Pass includeContent: true to include the sequence definition.

const sequence = await kraiter.sequences.get('seq_onboarding');

if (sequence) {
  console.log(sequence.name, sequence.enabled);
}

// Include the definition
const full = await kraiter.sequences.get('seq_onboarding', true);

Parameters

Returns

Promise<Sequence | SequenceWithContent | null> — the sequence object (with content when includeContent is true), or null if not found.

list

Lists sequences with cursor-based pagination. Optionally filter by enabled state.

const page = await kraiter.sequences.list({ enabled: true });

for (const sequence of page.items) {
  console.log(sequence.sequenceId, sequence.name, sequence.enabled);
}

Parameters

Returns

Promise<{ items: Sequence[]; nextCursor?: string }> — a page 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

Returns

Promise<Sequence> — the updated sequence object.

Errors

delete

Permanently deletes a sequence.

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

Parameters

Returns

Promise<void>

Errors

getStatus

Returns the enabled state and enrolment counts for a sequence. Returns null if not found.

const status = await kraiter.sequences.getStatus('seq_onboarding');

if (status) {
  console.log(status.enabled);            // true
  console.log(status.activeContacts);     // 340
  console.log(status.completedContacts);  // 910
  console.log(status.exitedContacts);     // 12
}

Parameters

Returns

Promise<SequenceStatus | null> — an object with sequenceId, enabled, activeContacts, completedContacts, and exitedContacts, or null if not found.

dryRun

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

const result = await kraiter.sequences.dryRun('seq_onboarding', {
  contactId: 'con_abc123',
});

for (const step of result.steps) {
  console.log(step.stepId, step.templateId, step.conditionResult?.passed);
}

Parameters

Returns

Promise<DryRunResult> — the simulated path:

Errors

listContacts

Lists the contacts currently enrolled in a sequence, with cursor-based pagination.

const page = await kraiter.sequences.listContacts('seq_onboarding');

for (const entry of page.items) {
  console.log(entry.email, entry.contactId, entry.status, entry.currentStepId);
}

Parameters

Returns

Promise<{ items: SequenceContactEntry[]; nextCursor?: string }> — a page of enrolled contact records.

listSends

Lists sends generated by a sequence, with cursor-based pagination. Optionally filter by date range and delivery status.

const page = await kraiter.sequences.listSends('seq_onboarding', {
  status: 'delivered',
  limit: 50,
});

for (const send of page.items) {
  console.log(send.contactId, send.templateId, send.deliveryStatus);
}

Parameters

Returns

Promise<{ items: SequenceSend[]; nextCursor?: string }> — a page of send records.

listVersions

Lists the version history for a sequence with cursor-based pagination. Each time a sequence is upserted, a new version is recorded.

const page = await kraiter.sequences.listVersions('seq_onboarding');

for (const version of page.items) {
  console.log(version.version, version.createdAt);
}

Parameters

Returns

Promise<{ items: SequenceVersion[]; nextCursor?: string }> — a page of version records.

Errors

getVersion

Retrieves a specific version of a sequence by its version identifier. Returns null if not found.

const version = await kraiter.sequences.getVersion('seq_onboarding', 'v3');

if (version) {
  console.log(version.version, version.createdAt);
  console.log(version.content); // the sequence definition at this version
}

Parameters

Returns

Promise<SequenceVersion | null> — the version record, or null if not found.

Errors