Skip to main content
POST
Early access. This API is available in early access. Contact us to turn it on for your workspace. Until it’s on, requests return 202 but no workflow runs.
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.

Authorizations

​
Authorization
string
header
required

Pass as Bearer <API_KEY>. Get API Key from SuprSend dashboard Developers -> API Keys section.

Body

application/json
​
list_id
string
required

ID of the list whose users you want to notify. Case-insensitive. The list must exist and be enabled.

Example:

"webinar-registrants"

​
workflow
string
required

Slug of the workflow to trigger. The workflow must exist in the workspace.

Example:

"webinar-reminder"

​
data
object

Variables used in the workflow and its templates, as {{key}}. The same data goes to every list member's run. Use $recipient.<property> in templates for per-user values.

Example:
​
tenant_id
string

ID of the tenant the runs belong to. Its branding and preferences apply to every run. Defaults to default. The tenant must exist.

Example:

"acme"

​
delay

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
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.

Example:

"2026-11-05T09:30:00Z"

​
cancellation_key
string

Key stored on every run started by this trigger, so a 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 instead, pass this request's $idempotency_key (or the message_id from the response) as idempotency_key.

Maximum string length: 512
Example:

"webinar-2026-11-05"

​
$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.

Example:

"webinar-reminder-2026-11-05"

Response

202 - Accepted

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
Example:

"success"

​
message_id
string

Unique identifier of the request generated by SuprSend.

Example:

"2b145020-f9b5-4b9c-a88f-882c27681adc"