Event Automation | Owlat Docs

Trigger automations with custom events for trial lifecycle, feature adoption, and more.

How it works

When you send an event via the API, Owlat checks if any active automation has a matching trigger. If it does, the automation runs for that contact — sending emails, adding tags, or waiting before the next step. You define the automations in the dashboard; your code just fires the events.

Plan your events

Define a consistent naming scheme before you start sending. Here's an example for a SaaS trial lifecycle:

Event name	When to fire	Suggested properties
`trial_started`	User creates account	`planName`, `trialDays`
`feature_activated`	User tries a key feature	`featureName`
`trial_expiring`	3 days before trial ends	`daysLeft`, `planName`
`trial_expired`	Trial period ends	`planName`
`plan_upgraded`	User converts to paid	`planName`, `mrr`

Naming conventions

Use snake_case for event names. Names must start with a letter and can contain letters, numbers, underscores, and hyphens (max 100 characters).

Send events

Trial started

import { Owlat } from '@owlat/sdk-js'

const owlat = new Owlat('lm_live_...')

await owlat.events.send({
  email: 'mira@acme.io',
  eventName: 'trial_started',
  eventProperties: {
    planName: 'Pro',
    trialDays: 14,
  },
})

curl -X POST https://your-deployment.convex.site/api/v1/events \
  -H "Authorization: Bearer lm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "mira@acme.io",
    "eventName": "trial_started",
    "eventProperties": {
      "planName": "Pro",
      "trialDays": 14
    }
  }'

Feature activated

await owlat.events.send({
  email: 'mira@acme.io',
  eventName: 'feature_activated',
  eventProperties: {
    featureName: 'team_invite',
  },
})

Trial expiring

await owlat.events.send({
  email: 'mira@acme.io',
  eventName: 'trial_expiring',
  eventProperties: {
    daysLeft: 3,
    planName: 'Pro',
  },
})

Auto-create contacts

If you fire events for users who might not exist as contacts yet, set createContactIfNotExists:

await owlat.events.send({
  email: 'new-lead@example.com',
  eventName: 'trial_started',
  eventProperties: { planName: 'Pro', trialDays: 14 },
  createContactIfNotExists: true,
})

The response tells you whether a contact was created:

{
  "data": {
    "eventId": "evt_m6e...",
    "contactId": "j57...",
    "eventName": "trial_started",
    "triggeredAutomations": 1,
    "contactCreated": true
  }
}

Setting up the automation

Once your code sends events, create the automation in the Owlat dashboard:

Go to Automations → New Automation
Set the trigger to Custom Event and enter the event name (e.g. trial_expiring)
Add steps — send an email, wait, send another, etc.
Publish the automation

Event properties are available as template variables in any email sent by the automation.

Next steps

Events API reference — full endpoint documentation
Contact Sync — ensure contacts exist before firing events
Automations guide — build multi-step flows in the dashboard