Events

Send custom events into SuperSend TX to trigger transactional automations.

Base URL: https://api.supersendtx.com

Authentication

Authorization: Bearer stx_…

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": "user@example.com",
  "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.

202 Accepted

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

• matched_automations = active automations whose trigger matched this event
• resumed_runs = waiting runs resumed by this event (wait_for_event)

Event shape

Inside automations, you can reference:

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

Typical flow

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

See also docs/api/automations.md.

SDK

import { SuperSendTX } from 'supersendtx'

const client = new SuperSendTX(process.env.SUPERSENDTX_API_KEY!)

await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: 'user@example.com',
  data: { name: 'Ada Lovelace' },
  idempotencyKey: 'evt_user_created_123',
})

CLI

SUPERSENDTX_API_KEY=$SUPERSENDTX_API_KEY npx -y --package=supersendtx-cli -- supersendtx events send \
  --name user.created \
  --email user@example.com \
  --user-id user_123 \
  --data '{"name":"Ada Lovelace"}'

OpenAPI

Machine-readable spec: openapi/supersendtx.yaml