Contacts

The kraiter.contacts namespace provides methods for managing your contact records — the people you send email to. Each contact has a unique ID, an email address, and an optional set of custom properties.

create

Creates a new contact.

const contact = await kraiter.contacts.create({
  email: 'alice@example.com',
  properties: {
    firstName: 'Alice',
    plan: 'pro',
  },
});

Parameters

Returns

Promise<Contact> — the newly created contact object.

Errors

get

Retrieves a contact by ID.

const contact = await kraiter.contacts.get('con_abc123');
console.log(contact.email);

Parameters

Returns

Promise<Contact> — the contact object.

Errors

getByEmail

Looks up a contact by email address. Returns null if no contact is found rather than throwing an error.

const contact = await kraiter.contacts.getByEmail('alice@example.com');

if (contact) {
  console.log(contact.id);
} else {
  console.log('Contact not found');
}

Parameters

Returns

Promise<Contact | null> — the contact object, or null if not found.

list

Lists contacts with optional filtering and pagination. Returns an async iterator.

for await (const contact of kraiter.contacts.list()) {
  console.log(contact.email);
}

Filter by search term:

for await (const contact of kraiter.contacts.list({ search: 'alice' })) {
  console.log(contact.email);
}

Parameters

Returns

AsyncIterable<Contact> — an async iterator that yields contact objects.

update

Updates an existing contact. Only the fields you include are changed; omitted fields are left untouched.

const updated = await kraiter.contacts.update('con_abc123', {
  properties: {
    plan: 'enterprise',
  },
});

Parameters

Returns

Promise<Contact> — the updated contact object.

Errors

delete

Permanently deletes a contact.

await kraiter.contacts.delete('con_abc123');

Parameters

Returns

Promise<void>

Errors

getSends

Retrieves the send history for a contact. Returns an async iterator of send records.

for await (const send of kraiter.contacts.getSends('con_abc123')) {
  console.log(send.templateId, send.sentAt, send.status);
}

Parameters

Returns

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

getScheduled

Retrieves scheduled sends for a contact. Returns an async iterator.

for await (const scheduled of kraiter.contacts.getScheduled('con_abc123')) {
  console.log(scheduled.templateId, scheduled.scheduledFor);
}

Parameters

Returns

AsyncIterable<ScheduledSend> — an async iterator of scheduled send records.

getSequences

Returns the sequences a contact is currently enrolled in.

const enrolments = await kraiter.contacts.getSequences('con_abc123');

for (const enrolment of enrolments) {
  console.log(enrolment.sequenceId, enrolment.status, enrolment.currentStep);
}

Parameters

Returns

Promise<SequenceEnrolment[]> — an array of sequence enrolment records.

getSegments

Returns the segments a contact belongs to.

const memberships = await kraiter.contacts.getSegments('con_abc123');

for (const membership of memberships) {
  console.log(membership.segmentId, membership.segmentName);
}

Parameters

Returns

Promise<SegmentMembership[]> — an array of segment membership records.

getTimeline

Returns a chronological feed of all events and interactions for a contact. Returns an async iterator.

for await (const entry of kraiter.contacts.getTimeline('con_abc123')) {
  console.log(entry.type, entry.timestamp, entry.data);
}

Parameters

Returns

AsyncIterable<TimelineEntry> — an async iterator of timeline entries.