---
title: "Ingest a custom event for automations"
method: POST
path: "/events"
tags: ["Events"]
---

# Ingest a custom event for automations

`POST /events`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/events`
- Auth: HTTP bearer

Starts a run on every active automation whose trigger matches the event name, resumes
runs waiting for this event, and cancels runs for the same person whose automation lists
it in `trigger.cancel_on_events`. An automation that matches but declines to enroll the
same person again (`trigger.once_per_contact` or `trigger.cooldown_days`) is counted in
`skipped_enrollments` and explained in `enrollment_skips`.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `name` string, required: Canonical event name (alias: `type`)
    - `type` string: Alias for name
    - `user_id` string
    - `userId` string: Alias for user_id
    - `email` string, email
    - `data` object: Event payload. Automations see it as sent. The stored event (and the `event` in the response) has credential values redacted to `"REDACTED"`: keys such as `password`, `secret`, `otp`, `api_key`, keys ending in `token`, `code` on login or verification events, and secret query parameters inside URL values. Sign-up source context (all optional) ties a conversion to where the person came from: `id` (your user or subscription id; repeats of the same event are recorded once), `visitor_id` (the `stx_vid` cookie), `gclid` / `gbraid` / `wbraid` (the ad click, from the `stx_ad` cookie), `came_from` (your own word for the source, shown as written), `signup_method`, `invited: true` (a teammate joining an existing account: a seat, not a sign-up, no conversion) and `internal: true` (your own team or a test: no conversion).
  - object
    - `name` string: Canonical event name (alias: `type`)
    - `type` string, required: Alias for name
    - `user_id` string
    - `userId` string: Alias for user_id
    - `email` string, email
    - `data` object: Event payload. Automations see it as sent. The stored event (and the `event` in the response) has credential values redacted to `"REDACTED"`: keys such as `password`, `secret`, `otp`, `api_key`, keys ending in `token`, `code` on login or verification events, and secret query parameters inside URL values. Sign-up source context (all optional) ties a conversion to where the person came from: `id` (your user or subscription id; repeats of the same event are recorded once), `visitor_id` (the `stx_vid` cookie), `gclid` / `gbraid` / `wbraid` (the ad click, from the `stx_ad` cookie), `came_from` (your own word for the source, shown as written), `signup_method`, `invited: true` (a teammate joining an existing account: a seat, not a sign-up, no conversion) and `internal: true` (your own team or a test: no conversion).

## Response `202`

Event accepted for automation processing, with counts of runs started, resumed, cancelled, and skipped

- TriggerEventResponse
  - `event` EventRecord, required
    - `id` string, required
    - `name` string, required
    - `user_id` string, nullable, required
    - `email` string, email, nullable, required
    - `data` object, required
    - `source` 'api' | 'dashboard' | 'on_site' | 'posthog' | 'mixpanel' | 'amplitude', required: Where the event came from: `api` (`POST /events` with an API key), `dashboard`, `on_site` (an on-site message on your website captured an email address), or `posthog`, `mixpanel`, `amplitude` (synced from a connected product-analytics account).
    - `created_at` string, date-time, required
  - `matched_automations` integer, required: Active automations whose trigger matched and that started a run for this event. Automations that matched but declined to enroll this person again are counted in `skipped_enrollments` instead.
  - `resumed_runs` integer, required: Waiting runs resumed by this event (`wait_for_event` steps)
  - `cancelled_runs` integer, required: Active runs cancelled because this event matched `trigger.cancel_on_events`
  - `skipped_enrollments` integer, required: Automations whose trigger matched but that did not enroll this person again because of `trigger.once_per_contact` or `trigger.cooldown_days`. 0 when none were skipped.
  - `enrollment_skips` EnrollmentSkip[]: One entry per skipped enrollment. Omitted when `skipped_enrollments` is 0.
    - `automation_id` string, required
    - `reason` 'once_per_contact' | 'cooldown', required: `once_per_contact` — the person already had a run on this automation. `cooldown` — the person had a run on this automation within the last `cooldown_days` days.
    - `prior_run_id` string, required: The earlier run that blocked this enrollment
    - `prior_run_at` string, date-time, required: When that earlier run was created

## Other responses

- `400`: Invalid event payload
- `401`: Missing or invalid API key / session
- `409`: Idempotency conflict

---

[API](https://skmtc.dev/ranla/apis/supersend-tx-api.md) · [All operations](https://skmtc.dev/ranla/apis/supersend-tx-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranla/apis/supersend-tx-api/revisions/e3e782652f50?raw)