> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Trigger Workflow on a List > 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. > [!NOTE] > > **Early access.** This API is available in early access. [Contact us](mailto:support@suprsend.com) to turn it on for your workspace. Until it's on, requests return `202` but no workflow runs. > [!WARNING] > > Use this API for lists of up to **1,000 users**. If the list has more, only the first 1,000 users (in the order they were added) get a run, and the rest are skipped without an error. To notify a larger list, use a [broadcast](https://docs.suprsend.com/reference/trigger-broadcast.md). ## OpenAPI ````yaml POST /trigger/list/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /trigger/list/: post: summary: Trigger Workflow on a List description: > 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. operationId: trigger-workflow-on-list requestBody: content: application/json: schema: type: object required: - list_id - workflow properties: list_id: type: string description: >- ID of the list whose users you want to notify. Case-insensitive. The list must exist and be enabled. example: webinar-registrants workflow: type: string description: >- Slug of the workflow to trigger. The workflow must exist in the workspace. example: webinar-reminder data: type: object description: >- 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. additionalProperties: true example: webinar_title: Scaling notifications in B2B apps join_url: https://example.com/webinar/join tenant_id: type: string description: >- 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. example: acme delay: oneOf: - type: string - type: integer description: > 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. example: 1h30m trigger_at: type: string format: date-time description: > 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. example: '2026-11-05T09:30:00Z' cancellation_key: type: string maxLength: 512 description: >- 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`. example: webinar-2026-11-05 $idempotency_key: type: string description: >- 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. example: webinar-reminder-2026-11-05 responses: '202': description: 202 - Accepted content: application/json: examples: Result: value: status: success message_id: 2b145020-f9b5-4b9c-a88f-882c27681adc schema: type: object description: >- 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. properties: status: type: string example: success message_id: type: string description: Unique identifier of the request generated by SuprSend. example: 2b145020-f9b5-4b9c-a88f-882c27681adc '400': description: 400 - Bad Request content: application/json: examples: Missing fields: value: status: error error: message: list_id and workflow are required type: bad_request Array body: value: status: error error: message: Bad request type: bad_request schema: type: object description: >- Returned when `list_id` or `workflow` is missing, the `Content-Type` header isn't `application/json`, or the body is a JSON array. Bulk (array) bodies are not supported on this endpoint. properties: status: type: string example: error error: type: object properties: message: type: string example: list_id and workflow are required type: type: string example: bad_request deprecated: false security: - BearerAuth: [] x-codeSamples: - lang: cURL label: Trigger now source: | curl --request POST \ --url 'https://hub.suprsend.com/trigger/list/' \ --header 'Authorization: Bearer __your_api_key__' \ --header 'Content-Type: application/json' \ --data '{ "list_id": "webinar-registrants", "workflow": "webinar-reminder", "data": { "webinar_title": "Scaling notifications in B2B apps", "join_url": "https://example.com/webinar/join" } }' - lang: cURL label: Schedule with trigger_at source: | curl --request POST \ --url 'https://hub.suprsend.com/trigger/list/' \ --header 'Authorization: Bearer __your_api_key__' \ --header 'Content-Type: application/json' \ --data '{ "list_id": "webinar-registrants", "workflow": "webinar-reminder", "trigger_at": "2026-11-05T09:30:00Z", "tenant_id": "acme", "cancellation_key": "webinar-2026-11-05", "data": { "webinar_title": "Scaling notifications in B2B apps", "join_url": "https://example.com/webinar/join" } }' components: securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.