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. You can identify the contact by contactId or email — at least one must be provided. If both are given, contactId takes precedence.

const event = await kraiter.events.track({
  name: 'plan_upgraded',
  contactId: 'con_abc123',
  properties: {
    previousPlan: 'free',
    newPlan: 'pro',
  },
});

Identifying by email

If you do not have the contact ID to hand, you can identify the contact by their email address instead:

const event = await kraiter.events.track({
  name: 'page_viewed',
  email: 'alice@example.com',
  properties: {
    url: '/pricing',
  },
});

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 event = await kraiter.events.track({
  name: 'signed_up',
  contactId: 'con_abc123',
  timestamp: '2025-06-15T10:30:00Z',
});

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	The event name. Use a consistent naming convention such as `snake_case`.
`contactId`	`string`	No	The ID of the contact to associate the event with. At least one of `contactId` or `email` is required.
`email`	`string`	No	The email address of the contact. Used when `contactId` is not available. At least one of `contactId` or `email` is required.
`properties`	`Record<string, unknown>`	No	Arbitrary key-value pairs of event data.
`timestamp`	`string`	No	ISO 8601 timestamp. Defaults to the current time.

Returns

Promise<Event> — the recorded event object.

Event object

Field	Type	Description
`id`	`string`	Unique event ID.
`name`	`string`	The event name.
`contactId`	`string`	The contact this event is associated with.
`properties`	`Record<string, unknown>`	Event properties.
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred.
`createdAt`	`string`	ISO 8601 timestamp of when the event was recorded.

Errors

Code	When
`NOT_FOUND`	The specified `contactId` or `email` does not match any contact.
`VALIDATION_ERROR`	The event name is missing or one of `contactId`/`email` is invalid.

Error handling example

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

try {
  await kraiter.events.track({
    name: 'purchase_completed',
    email: 'unknown@example.com',
    properties: { amount: 99.99 },
  });
} catch (error) {
  if (error instanceof KraiterError && error.code === 'NOT_FOUND') {
    console.error('Contact not found — create the contact first');
  } else {
    throw error;
  }
}

Events can act as triggers for sequence automations. When you track an event whose name matches a sequence trigger, enrolled 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.