SuprSend Trigger API
The Trigger API from SuprSend — 2 operation(s) for trigger.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast Trigger API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Trigger
paths:
/{workspace_key}/trigger/:
post:
summary: Dynamic Workflow Trigger
security:
- BearerAuth: []
description: API to dynamically create and trigger a single step workflow.
operationId: dynamic-workflow-trigger
parameters:
- name: workspace_key
in: path
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- template
- notification_category
- users
properties:
name:
type: string
description: Unique name of the workflow. The workflow name should be easily identifiable for your reference at a later stage. You can see workflow-related analytics on the workflow page (how many notifications were sent, delivered, clicked or interacted).
default: _workflow_name_
template:
type: string
description: Unique slug of the template created on SuprSend dashboard. You can get this by clicking on the clipboard icon next to the Template name on SuprSend templates page.
default: _template_slug_
notification_category:
type: string
description: Used to apply user category level [preferences]("/docs/user-preferences") on notification trigger.
default: transactional
users:
type: array
description: Array object of target users.
items:
properties:
distinct_id:
type: string
description: unique identifier of the user
default: _distinct_id_
$channels:
type: array
description: send notification on selected channels in user profile. Following channel keys can be used - email, sms, whatsapp, androidpush, iospush, slack, webpush
default: []
items:
type: string
$email:
type: array
description: To trigger notification on a particular email
default: []
items:
type: string
$sms:
type: array
description: Send SMS on a particular number.
default: []
items:
type: string
$whatsapp:
type: array
description: Send Whatsapp on a particular number.
default: []
items:
type: string
$androidpush:
type: array
description: Send androidpush on the given push token
items:
type: string
$iospush:
type: array
description: Send iOSpush on the given push token
items:
type: string
$slack:
type: array
description: Slack channel configuration
items:
oneOf:
- type: object
title: user email_id
required:
- email
- access_token
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: user member_id
required:
- user_id
- access_token
properties:
user_id:
type: string
description: Slack user ID (U/WXXXXXXXX format)
example: U/WXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: Slack channel
required:
- channel
- access_token
properties:
channel:
type: string
description: Slack channel ID (CXXXXXXXX format)
example: CXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Slack incoming webhook URL
example: https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX
$ms_teams:
type: array
description: Microsoft Teams channel configuration
items:
oneOf:
- type: object
title: MS Teams using conversation ID
required:
- tenant_id
- service_url
- conversation_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
conversation_id:
type: string
description: Microsoft Teams conversation ID
example: 19:c1524d7c-a06f-456f-8abe-xxxx
- type: object
title: MS Teams using user ID
required:
- tenant_id
- service_url
- user_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
user_id:
type: string
description: Microsoft Teams user ID
example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx
- type: object
title: MS Teams using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Microsoft Teams incoming webhook URL
example: https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX
required:
- distinct_id
type: object
data:
type: object
description: variable data required to render dynamic template content or workflow properties like dynamic delay or channel override in send node.
properties:
$attachments:
type: array
description: Use this key to pass email attachment in the trigger. You can either pass attachment as a public URL or as a base64-encoded file (limit < 50KB).
items:
oneOf:
- type: object
title: publicly accessible URL
description: Pass file as **publicly accessible URL** (No limit on file size)
required:
- url
properties:
url:
type: string
format: uri
description: Publicly accessible URL of the file
example: https://bitcoincore.org/bitcoin.pdf
filename:
type: string
description: Filename to be shown in email
example: billing.pdf
ignore_if_error:
type: boolean
description: Ignore the attachment if it fails to load
- type: object
title: base64-encoded file
description: Pass file as a **base-64 file** (supported limit < 50KB)
required:
- data
properties:
data:
type: string
description: Base64-encoded content of the file
filename:
type: string
description: Filename to be shown in email
contentType:
type: string
example: application/pdf
additionalProperties:
type: string
delivery:
type: object
description: delivery instructions for the workflow. You can set [Smart Delivery](https://docs.suprsend.com/docs/smart-delivery) preference by setting "smart":true
properties:
smart:
type: boolean
description: You can enable smart delivery by setting it true
default: false
success:
type: string
description: Success event for stopping further notification in case smart is set to true. You can set notification status like delivery, interaction or custom success event
default: seen
time_to_live:
type: string
description: 'Time window to define delay between subsequent channel trigger in case of smart delivery.
Delay = `time_to_live / (number_of_channels - 1)`. Format - `XXdXXhXXmXXs` or if its number (n) then delay is in seconds (n)
'
mandatory_channels:
type: array
description: Channels on which notification has to be sent immediately in case of smart delivery. Following channel keys can be used - email, sms, whatsapp, androidpush, iospush, slack, webpush
items:
type: string
delay:
type: string
description: Workflow will be halted for the time mentioned in delay, and become active once the delay period is over. Format - `XXdXXhXXmXXs` or if its number (n) then delay is in seconds (n)
trigger_at:
type: string
description: Trigger workflow on a specific date-time. Format - date string in ISO 8601 e.g. "2022-08-27T20:14:51.643Z"
format: date
tenant_id:
type: string
description: string identifier of the tenant this workflow is associated with
$idempotency_key:
type: string
description: Unique identifier of the request (deduplicates request for 24hrs)
x-codeSamples:
- lang: cURL
label: Dynamic Workflow Trigger
source: "curl -X POST \"https://hub.suprsend.com/{workspace_key}/dynamic-workflow/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Welcome Email Workflow\",\n \"template\": \"welcome-email-template\",\n \"notification_category\": \"transactional\",\n \"users\": [\n {\n \"distinct_id\": \"user123\",\n \"$email\": [\"user@example.com\"],\n \"$channels\": [\"email\"]\n }\n ],\n \"data\": {\n \"user_name\": \"John Doe\",\n \"welcome_message\": \"Welcome to our platform!\"\n }\n }'\n"
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value: Accepted - OK
schema:
type: string
example: Accepted - OK
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
status: fail
message: BAD REQUEST
schema:
type: object
properties:
status:
type: string
example: fail
description: Indicates the failure status of the request.
message:
type: string
example: BAD REQUEST
description: Describes the reason for the failure.
deprecated: false
tags:
- Trigger
/trigger/:
post:
summary: Trigger Workflow (single or bulk)
security:
- BearerAuth: []
description: 'API to trigger multi-step workflow to one or more users/objects by passing workflow slug, via `POST /trigger/`.
Send a single JSON **object** to trigger one workflow, or an array of objects to trigger multiple workflows in one call.
'
operationId: trigger-workflow-api
x-codeSamples:
- lang: cURL
label: Trigger Workflow
source: "curl --request POST \\\n --url 'https://hub.suprsend.com/trigger/' \\\n --header 'Authorization: Bearer __your_api_key__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"workflow\": \"demo_notification_workflow\",\n \"recipients\": [\n {\n \"distinct_id\": \"user123\",\n \"$email\": [\"user@example.com\"]\n }\n ],\n \"data\": {\n \"user_name\": \"John Doe\",\n \"welcome_message\": \"Welcome to our platform!\"\n }\n }'\n"
- lang: cURL
label: Bulk Trigger Workflows
source: "curl --request POST \\\n --url 'https://hub.suprsend.com/trigger/' \\\n --header 'Authorization: Bearer __your_api_key__' \\\n --header 'Content-Type: application/json' \\\n --data '[\n {\n \"workflow\": \"demo_notification_workflow\",\n \"recipients\": [\n {\n \"distinct_id\": \"user123\",\n \"$email\": [\"user@example.com\"]\n }\n ],\n \"data\": {\n \"user_name\": \"John Doe\",\n \"welcome_message\": \"Welcome to our platform!\"\n }\n },\n {\n \"workflow\": \"demo_notification_workflow\",\n \"recipients\": [\n {\n \"distinct_id\": \"user123\",\n \"$email\": [\"user@example.com\"]\n }\n ],\n \"data\": {\n \"user_name\": \"John Doe\",\n \"welcome_message\": \"Welcome to our platform!\"\n }\n }\n ]'\n"
requestBody:
content:
application/json:
schema:
oneOf:
- title: Single workflow trigger
description: Send a single workflow trigger object as the request body.
$ref: '#/components/schemas/WorkflowTriggerSingleBody'
- title: Bulk workflow trigger
type: array
description: 'Send a JSON **array** of workflow trigger objects (instead of a single JSON **object**) to trigger multiple workflows in one request. Each array item uses the same payload structure as a single workflow trigger (see **Single workflow trigger**).
Each record is independent - `workflow` (workflow slug), `recipients`, `tenant_id`, and `data` (including `data.$attachments` for email attachments) can all differ per record.
**Limits:**
- Maximum **800 KB** total request body size.
- Maximum **100 records** per request. Behavior beyond these limits is undefined.
**Rate limits:** A bulk request counts as **N calls** (one per record), not one call, against your rate limit.
Returns **207 Multi-Status** with per-record outcomes. See the `207` response below.
'
maxItems: 100
items:
$ref: '#/components/schemas/WorkflowTriggerSingleBody'
responses:
'202':
description: 202 - Accepted (returned for single workflow trigger requests).
content:
application/json:
examples:
Result:
value:
message_id: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status: success
schema:
type: object
description: All workflow requests will be accepted as long as the API request is correct. To verify if the execution was successful, check the 'Requests' tab under the 'Logs' section on the SuprSend dashboard.
properties:
message_id:
type: string
description: Unique identifier of the message generated by SuprSend.
example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status:
type: string
example: success
'207':
description: 207 - Multi-Status (returned for bulk workflow trigger requests). Inspect each record's `status` and `error` for individual outcomes.
content:
application/json:
examples:
Result:
value:
records:
- status: success
message_id: a1b2c3d4-e5f6-7890-abcd-ef0123456789
status_code: 202
- status: error
status_code: 404
error:
message: workflow not found
type: not_found
status: success
schema:
type: object
description: Per-record outcomes for a bulk workflow trigger request. Each item in `records` corresponds to the workflow at the same index in the request array.
properties:
records:
type: array
description: Per-record outcomes, in the same order as the request array.
items:
type: object
properties:
status:
type: string
enum:
- success
- error
description: Per-record status. `success` means the workflow was accepted; `error` means it was rejected.
status_code:
type: integer
description: Per-record HTTP-style status code (for example, `202` for accepted, `404` for workflow not found).
message_id:
type: string
description: Unique identifier of the message generated by SuprSend. Present only when `status` is `success`.
error:
type: object
description: Present only when `status` is `error`.
properties:
message:
type: string
description: Human-readable error message for the failed record.
type:
type: string
description: Machine-readable error type (for example, `not_found`).
status:
type: string
description: Top-level status returned by the API. Inspect each record's `status` and `error` to determine per-record outcomes.
example: success
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
status: fail
message: BAD REQUEST
schema:
type: object
description: This error would come if the API request format is incorrect.
properties:
status:
type: string
example: fail
message:
type: string
example: BAD REQUEST
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
status: fail
message: workflow 'workflow_slug' not found
schema:
type: object
description: This error would come if the workflow slug is not found.
properties:
status:
type: string
example: fail
message:
type: string
example: workflow 'workflow_slug' not found
deprecated: false
tags:
- Trigger
components:
schemas:
WorkflowTriggerSingleBody:
type: object
description: A single workflow trigger payload. Send this object as-is for a single workflow trigger, or wrap multiple instances in a JSON array for a bulk trigger.
required:
- workflow
- recipients
properties:
workflow:
type: string
description: You can get workflow slug from workflow settings on SuprSend dashboard.
default: _workflow_slug_
recipients:
type: array
description: List of recipients to be notified. You can either add recipient as array of distinct_ids or array of recipient objects. You can add up to 100 recipients in a single API.
items:
oneOf:
- type: object
title: Identify user inline
description: You can pass user properties and channels inline in workflow trigger request. Properties and channels passed here also update in user profile on workflow trigger.
required:
- distinct_id
properties:
is_transient:
type: boolean
description: set `is_transient = true` to send notification to anonymous user. You don't need to pass `distinct_id` for anonymous sending.
distinct_id:
type: string
description: unique identifier of the user who needs to be notified
default: id1
$channels:
type: array
items:
type: string
example: email
description: channel to send notification to
enum:
- email
- sms
- inbox
- androidpush
- iospush
- slack
- ms_teams
- webpush
- whatsapp
$email:
type: array
items:
type: string
format: email
example: john@example.com
$sms:
type: array
items:
type: string
example: '+1234567890'
$inbox:
type: array
items:
type: string
example: 4nlPk4t4kurG5kChxxxx
$androidpush:
type: array
items:
type: string
example: __android_push_token__
$iospush:
type: array
items:
type: string
example: __ios_push_token__
$slack:
type: array
description: Slack channel configuration
items:
oneOf:
- type: object
title: Slack using email
required:
- email
- access_token
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: Slack using member ID
required:
- user_id
- access_token
properties:
user_id:
type: string
description: Slack user ID (U/WXXXXXXXX format)
example: U/WXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using channel
required:
- channel
- access_token
properties:
channel:
type: string
description: Slack channel ID (CXXXXXXXX format)
example: CXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Slack incoming webhook URL
example: https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX
$ms_teams:
type: array
description: Microsoft Teams channel configuration
items:
oneOf:
- type: object
title: MS Teams using conversation ID
required:
- tenant_id
- service_url
- conversation_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
conversation_id:
type: string
description: Microsoft Teams conversation ID
example: 19:c1524d7c-a06f-456f-8abe-xxxx
- type: object
title: MS Teams using user ID
required:
- tenant_id
- service_url
- user_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
user_id:
type: string
description: Microsoft Teams user ID
example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx
- type: object
title: MS Teams using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Microsoft Teams incoming webhook URL
example: https://wnk1z.webhook.office.com/webhookb2/XXX
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-trigger-api-openapi.yml