Events

The kraiter.events namespace lets you record custom events against contacts. Events can trigger sequence automations, feed the contact timeline, and power segment rules.

track

Tracks a custom event. The contact is identified by email — if no contact exists with that address, one is resolved or created server-side as part of tracking.

const result = await kraiter.events.track({
  name: 'plan_upgraded',
  email: 'alice@example.com',
  properties: {
    previousPlan: 'free',
    newPlan: 'pro',
  },
});

console.log(result.contactId);          // the resolved contact
console.log(result.triggeredSequences); // sequences this event started

Custom timestamp

By default the event timestamp is set to the current time. You can override it with an ISO 8601 string to back-date events — useful when importing historical data.

const result = await kraiter.events.track({
  name: 'signed_up',
  email: 'alice@example.com',
  timestamp: '2025-06-15T10:30:00Z',
});

Parameters

Returns

Promise<TrackEventResult> — the tracking result:

Event object

Errors

Error handling example

import { MailerError } from '@kraiter/sdk';

try {
  await kraiter.events.track({
    name: 'purchase_completed',
    email: 'alice@example.com',
    properties: { amount: 99.99 },
  });
} catch (error) {
  if (error instanceof MailerError && error.code === 'VALIDATION_ERROR') {
    console.error('Invalid event:', error.message);
  } else {
    throw error;
  }
}

list

Lists tracked events across your tenant, one page at a time. Optionally filter by event name.

const page = await kraiter.events.list({ name: 'plan_upgraded', limit: 50 });

for (const event of page.items) {
  console.log(event.eventId, event.name, event.timestamp);
}

Parameters

Returns

Promise<{ items: Event[]; nextCursor?: string }> — a page of events.

listForContact

Lists events recorded for a single contact.

const page = await kraiter.events.listForContact('con_abc123', { limit: 50 });

for (const event of page.items) {
  console.log(event.name, event.timestamp);
}

Parameters

Returns

Promise<{ items: Event[]; nextCursor?: string }> — a page of events for the contact.

Usage with sequences

Events can act as triggers for sequence automations. When you track an event whose name matches a sequence trigger, matching contacts will advance through the sequence automatically. See the Sequences guide for details on configuring event-based triggers.

Best practices

• Use consistent event names. Stick to a naming convention like snake_case (e.g. plan_upgraded, invoice_paid). This makes it easier to build segment rules and sequence triggers.
• Keep properties flat. Deeply nested objects are harder to query. Prefer { planName: 'pro', amount: 49 } over { plan: { name: 'pro', pricing: { amount: 49 } } }.
• Batch historical imports. When importing past events, set the timestamp field to preserve the original event time.