Events

Events are actions or occurrences associated with a contact. Kraiter supports both custom events you send via the API and system events generated automatically when emails are sent, opened, clicked, bounced, or complained about.

Events are the primary mechanism for triggering sequence enrolments and building a timeline of contact activity.

Sending custom events

Track a custom event by providing the contact's email and an event name. You can optionally include properties with additional context.

await kraiter.events.track({
  email: 'alice@example.com',
  event: 'purchase.completed',
  properties: {
    orderId: 'ORD-12345',
    amount: 79.99,
    currency: 'GBP',
    items: 3,
  },
});

curl -X POST https://api.kraiter.com/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "event": "purchase.completed",
    "properties": {
      "orderId": "ORD-12345",
      "amount": 79.99,
      "currency": "GBP",
      "items": 3
    }
  }'

Event naming conventions

Use dot-separated names to organise events into categories:

• purchase.completed, purchase.refunded
• feature.activated, feature.deactivated
• onboarding.step1, onboarding.step2, onboarding.completed

Event names are case-sensitive. Choose a consistent naming pattern and stick with it.

Event properties

Properties are arbitrary key-value pairs attached to an event. They are stored with the event and can be used for filtering and analysis. Property values can be strings, numbers, or booleans.

Auto-contact creation

When you send an event for an email address that does not exist as a contact, Kraiter automatically creates the contact. This is useful for tracking events from anonymous users who later become contacts.

// This creates the contact if it doesn't exist
await kraiter.events.track({
  email: 'new-user@example.com',
  event: 'signup.started',
});

The auto-created contact will have no custom properties — just the email address and the event record. You can update the contact's properties later.

System events

Kraiter automatically generates events for email lifecycle activities. These events use the email.* namespace:

System events are created automatically and cannot be sent via the API. They include metadata such as the send ID, template ID, and sequence ID (if applicable).

Using events to trigger sequences

Events are a key way to start automated sequences. When defining a sequence, you can set an event-based trigger so that contacts are automatically enrolled when a matching event is received.

trigger:
  event: purchase.completed

steps:
  - action: email
    template: order-confirmation
  - action: delay
    duration: 3d
  - action: email
    template: review-request

In this example, whenever a purchase.completed event is tracked for a contact, they are enrolled in the sequence and receive the order confirmation email immediately, followed by a review request three days later.

See the Sequences guide for more on triggers and conditions.

Listing events

Retrieve events for a specific contact:

const { items, nextCursor } = await kraiter.events.list({
  email: 'alice@example.com',
  limit: 25,
});

curl "https://api.kraiter.com/events?email=alice%40example.com&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can filter by event name:

const purchases = await kraiter.events.list({
  email: 'alice@example.com',
  event: 'purchase.completed',
});

Tenant-wide event feed

Kraiter provides a live feed of events across all contacts in your tenant. This is useful for monitoring activity in real time from the dashboard.

Events are retained for your tenant's retention period. Older events are automatically archived.

Best practices

• Be specific with event names. purchase.completed is better than purchase because it leaves room for purchase.started, purchase.refunded, etc.
• Include relevant properties. Properties make events useful for analysis. Include identifiers (order IDs, plan names) and values (amounts, counts).
• Do not include sensitive data. Avoid putting passwords, tokens, or personally identifiable information beyond the email address in event properties.
• Use events for sequence triggers. Rather than manually enrolling contacts in sequences via the API, use events to automate enrolment based on user behaviour.