Events

Send custom events into Ranla to trigger transactional automations.

Base URL: https://api.ranla.ai

Authentication

Authorization: Bearer rnl_…

Dashboard session cookies also work for browser requests to /api/events, which is how the automations canvas editor sends test events.

Trigger an event

POST /events

{
  "name": "user.created",
  "user_id": "user_123",
  "email": "[email protected]",
  "data": {
    "name": "Ada Lovelace",
    "plan": "pro"
  }
}

type is accepted as an alias for name.

Idempotency

Use Idempotency-Key for replay-safe retries:

Idempotency-Key: evt_user_created_123

Retries with the same key and body return the original response. Reusing the key with a different body returns HTTP 409.

Keys are kept for 24 hours. After that, the same key is accepted as a new event, so a key such as user.activated:<userId> does not make an event fire once per person. For once-only events, emit from the moment the state changes (the write that first sets activatedAt), or check a flag your app already stores.

202 Accepted

{
  "event": {
    "id": "ae_123",
    "name": "user.created",
    "user_id": "user_123",
    "email": "[email protected]",
    "data": {
      "name": "Ada Lovelace",
      "plan": "pro"
    },
    "source": "api",
    "created_at": "2026-07-26T12:00:00.000Z"
  },
  "matched_automations": 2,
  "resumed_runs": 1,
  "cancelled_runs": 0
}

matched_automations = active automations whose trigger matched this event
resumed_runs = waiting runs resumed by this event (wait_for_event)
cancelled_runs = active runs cancelled because this event matched trigger.cancel_on_events

Event shape

Field	Type	Notes
`name`	string	Required unless `type` is provided
`type`	string	Alias for `name`
`user_id`	string	Optional identity hint for wait/resume matching
`email`	string	Optional identity hint for wait/resume matching
`data`	object	Optional event payload used by conditions and email templates
`dry_run`	boolean	Dashboard only — with `automation_id`, runs that one automation even if draft/paused; skips delays/waits and stubs email/SMS
`test_send`	boolean	Dashboard only — with `automation_id`, same targeting as dry-run but sends real email/SMS; still skips delays/waits. Mutually exclusive with `dry_run`
`automation_id`	string	Required with `dry_run` or `test_send`; rejected on API-key requests

Inside automations, you can reference:

{{event.name}}
{{event.email}}
{{event.user_id}}
{{event.data.foo}}

Credentials in data. Automations triggered by the event see data exactly as you sent it, so a step can mail a login code with {{event.data.code}}. The stored copy of the event is redacted: values under credential keys (password, secret, otp, api_key, anything ending in token, and code on login or verification events such as auth.code_requested), plus secret query parameters inside URL values, are stored as "REDACTED". The event in the response shows the stored copy. Segments and event reports read the stored copy, so they can never match on a credential.

Typical flow

Create an automation (dashboard canvas, POST /automations, or supersendtx automations create) with trigger user.created
Activate it (POST /automations/{id} with { "action": "activate" })
Send POST /events from your app when that business event happens
Ranla queues the run in Bull/Redis
Send-email steps flow through the same transactional send path as POST /emails

SDK

import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: '[email protected]',
  data: { name: 'Ada Lovelace' },
  idempotencyKey: 'evt_user_created_123',
})

CLI

RANLA_API_KEY=$RANLA_API_KEY npx -y --package=ranla-cli -- ranla events send \
  --name user.created \
  --email [email protected] \
  --user-id user_123 \
  --data '{"name":"Ada Lovelace"}'

OpenAPI

Machine-readable spec: openapi/supersendtx.yaml