--- title: "Trigger Workflow on a List" method: POST path: "/trigger/list/" --- # Trigger Workflow on a List `POST /trigger/list/` ## Request - Base URL: `https://hub.suprsend.com` - URL: `https://hub.suprsend.com/trigger/list/` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) API to trigger a workflow for every user in a [list](/docs/lists) in one call, via `POST /trigger/list/`. SuprSend starts one workflow run per list member, with that user as the recipient. Every run gets the same `data` and `tenant_id`. Members are read when the trigger runs: right away, or after `delay` / at `trigger_at` if you schedule it. Dynamic lists are synced before running the workflow or fetching the list of users. ## Request body - object - `list_id` string, required: ID of the list whose users you want to notify. Case-insensitive. The list must exist and be enabled. - `workflow` string, required: Slug of the workflow to trigger. The workflow must exist in the workspace. - `data` object: Variables used in the workflow and its templates, as `{{key}}`. The same `data` goes to every list member's run. Use `$recipient.` in templates for per-user values. - `tenant_id` string: ID of the [tenant](/docs/tenants) the runs belong to. Its branding and preferences apply to every run. Defaults to `default`. The tenant must exist. - `delay` union: Wait this long before triggering. Pass a duration string in the format `XXdXXhXXmXXs` (for example, `1h30m`) or a number of seconds (for example, `5400`). Maximum 15 days. - string - integer - `trigger_at` string, date-time: Trigger at this date-time, in ISO 8601 format with a timezone (for example, `2026-11-05T09:30:00Z`). Maximum 15 days from now. If `trigger_at` is in the future, it wins over `delay`. If it's in the past, `delay` applies when set; otherwise the workflow triggers right away. - `cancellation_key` string: Key stored on every run started by this trigger, so a [Cancel Workflow](/docs/cancel-workflow) node can stop those runs. This value overrides the workflow's Trigger-node cancellation key expression. To cancel the runs through the [Cancel Workflow API](/reference/cancel-workflow) instead, pass this request's `$idempotency_key` (or the `message_id` from the response) as `idempotency_key`. - `$idempotency_key` string: Unique key for this request, up to 255 characters. Another request with the same key within 24 hours is ignored, so retries don't notify the list twice. ## Response `202` 202 - Accepted - object: The request is accepted as long as its format is correct. These problems are reported later, in the **Requests** tab under **Logs** on the SuprSend dashboard - a missing list, workflow or tenant, a disabled list, an invalid `delay`, a `trigger_at` that isn't ISO 8601, or a schedule more than 15 days out. - `status` string - `message_id` string: Unique identifier of the request generated by SuprSend. ## Other responses - `400`: 400 - Bad Request ## Changes - **2026-10-27** `9e64cbe802a5`: 1 info - endpoint added [Operation history](https://skmtc.dev/suprsend/apis/suprsend-api/changes/trigger/list/post.md) --- [API](https://skmtc.dev/suprsend/apis/suprsend-api.md) - [All operations](https://skmtc.dev/suprsend/apis/suprsend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/suprsend/apis/suprsend-api/revisions/9e64cbe802a5?raw)