The SuprSend REST API allows developers to programmatically trigger notification workflows, manage users and subscribers, send broadcast notifications, and access delivery logs. Authentication uses workspace key and secret credentials. The API returns HTTP 202 on successful workflow triggers and supports up to 100 recipients per single workflow trigger call.
openapi: 3.1.1
info:
title: SuprSend API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API_Key # Just for documentation, doesn't enforce behavior
description: "Pass as `Bearer <API_KEY>`. Get API Key from SuprSend dashboard Developers -> API Keys section."
ServiceTokenAuth:
type: apiKey
in: header
name: ServiceToken <token>
description: You can get Service Token from [SuprSend dashboard -> Account Settings -> Service Tokens](https://app.suprsend.com/en/account-settings/service-tokens) section.
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer
description: Bearer authentication header of the form `Bearer <token>`, where <token> is your auth token.
schemas:
TemplateVariant:
type: object
properties:
$schema:
type: string
description: Schema URL for variant validation.
example: "https://schema.suprsend.com/template/v2/variant_schema.json"
channel:
type: string
description: Channel this variant belongs to.
example: "email"
id:
type: string
description: Variant identifier.
example: "default"
tenant_id:
type: string
nullable: true
description: Tenant this variant is scoped to, or null for default.
locale:
type: string
description: Locale code.
example: "en"
conditions:
type: array
description: Conditions for variant selection at send time.
items:
type: object
hash:
type: string
description: Content hash for change detection.
needs_vendor_approval:
type: boolean
description: Whether this variant requires vendor approval (SMS DLT, WhatsApp).
sysgen_template_name:
type: string
nullable: true
description: System-generated template name for vendor approval.
approval_status:
type: string
enum: ["auto_approved", "pending", "sent_for_approval", "approved", "rejected"]
description: Current approval status of the variant.
discard_comment:
type: string
nullable: true
description: Reason provided when a variant is discarded.
approval_at:
type: string
format: date-time
nullable: true
description: Timestamp when the variant was approved.
has_error:
type: boolean
description: Whether the variant has validation errors.
seq_no:
type: integer
description: Ordering within the channel + tenant + locale combination.
action:
type: string
nullable: true
description: Action taken in the latest commit (Updated, Added, Unchanged, or null).
created_at:
type: string
format: date-time
description: Timestamp when the variant was created.
content:
type: object
description: Channel-specific content. Structure varies by channel. Only returned in variant detail endpoint.
vendor_approvals:
type: array
description: Vendor approval entries (WhatsApp/SMS only). Only returned in variant detail endpoint.
items:
type: object
Workflow:
type: object
properties:
$schema:
type: string
format: uri
description: Schema URL for workflow validation
example: "https://schema.suprsend.com/workflow/v1/schema.json"
slug:
type: string
description: Unique identifier for the workflow
minLength: 1
maxLength: 255
pattern: "^[a-z0-9-_]+$"
example: "welcome-sequence"
is_enabled:
type: boolean
description: Whether the workflow is enabled
example: true
created_at:
type: string
format: date-time
description: When the workflow was created
last_executed_at:
type: string
format: date-time
description: When the workflow was last executed
nullable: true
name:
type: string
description: Human-readable name of the workflow
example: "Welcome Sequence"
description:
type: string
nullable: true
description: Description explaining the usecase of the workflow
updated_at:
type: string
format: date-time
description: When the workflow was last updated
commit_message:
type: string
nullable: true
description: Last commit message
hash:
type: string
nullable: true
description: Git-like hash for version tracking
status:
type: string
enum: ["active", "inactive", "draft"]
description: Current status of the workflow
category:
type: string
description: Notification category of the workflow. Used to apply category-specific settings and preferences.
example: "transactional"
tags:
type: array
items:
type: string
description: Tags for organizing and filtering workflows in API.
ratelimit:
type: object
nullable: true
description: Workflow [throttle](https://docs.suprsend.com/docs/throttle) settings. This is used to limit the number of times a workflow can be executed per user in a given time period.
conditions:
type: array
items:
type: object
description: Trigger Conditions for workflow execution. Workflow will only be executed if trigger conditions evaluate to true.
trigger_type:
type: string
enum: ["event", "dynamic", "api"]
description: How the workflow is triggered. You can refer to all trigger types [here](https://docs.suprsend.com/reference/trigger-workflows#trigger-types).
trigger_events:
type: array
items:
type: string
description: Events that trigger this workflow. This will be set for trigger_type = `event`.
override_recipients_type:
type: string
nullable: true
description: Type of recipient override. Define whether to override and run this workflow for user, list of users or a single object.
enum: ["user", "single_object_fields"]
override_recipients_user_expr:
type: string
nullable: true
description: Expression for overriding recipients when override_recipients_type = `user`.
override_recipients_single_object_fields_expr:
type: string
nullable: true
description: Expression for overriding recipients when override_recipients_type = `single_object_fields`.
override_actor_user_expr:
type: string
nullable: true
description: Expression for overriding actor
override_tenant_expr:
type: string
nullable: true
description: Expression for overriding tenant
active_at:
type: string
format: date-time
description: When the workflow's live version became active. Will be `null` for draft version.
updated_by:
type: object
nullable: true
properties:
name:
type: string
description: Name of the user who last updated the workflow
email:
type: string
format: email
description: Email of the user who last updated the workflow
description: User who last updated the workflow
tree:
type: object
description: Node tree structure of the workflow. Shows the list of all nodes used in the workflow along with their configuration.
validation_result:
type: object
properties:
is_valid:
type: boolean
description: true if the workflow tree is valid to be published.
errors:
type: array
items:
type: string
description: List of errors if the workflow tree is not valid.
description: Validation status of the workflow
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: "[email protected]"
$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: "[email protected]"
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/XXXXXXXXX"
$timezone:
type: string
example: "America/New_York"
$locale:
type: string
example: "en_GB"
- type: object
title: "Notify object"
required: [id,object_type]
properties:
id:
type: string
description: Unique identifier of the object
example: frontend
object_type:
type: string
description: Filename to be shown in email
additionalProperties:
type: string
description: You can pass other user properties similar to recipient payload. It will be used when notification is sent to object channels as $recipient.<property>.
actor:
type: object
description: Includes distinct_id and properties of the user who performed the action. You can use it for [cross-user notifications]("https://docs.suprsend.com/docs/trigger-workflow#sending-cross-user-notifications"). Actor properties can be added as `$actor.<prop>`.
properties:
is_transient:
type: boolean
description: set `is_transient = true` to pass anonymous actor. You don't need to pass `distinct_id` for anonymous user.
distinct_id:
type: string
description: unique identifier of the actor who performed the action
default: id1
additionalProperties:
type: string
description: You can pass additional actor properties as `"user_prop1":"value1"` . Extra properties will be update in user profile which can then be used in the template as `$actor.<property>`.
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: "Pass Public 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: "Pass Base64 File Locally"
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
tenant_id:
type: string
description: string identifier of the tenant/tenant this workflow is associated with. Used to trigger [multi-tenant](https://docs.suprsend.com/docs/tenant-workflows) notifications
$idempotency_key:
type: string
description: Idempotency_key (valid for 24hrs)
DigestNode:
type: object
description: "[**Digest**](https://docs.suprsend.com/docs/digest): Batches and sends summary notifications at a recurring digest schedule."
required:
- node_type
- name
- schedule_type
properties:
name:
type: string
description: Human-readable name of the node
example: "Daily digest"
node_type:
type: string
const: digest
description:
type: string
nullable: true
description: Description of what this node does
schedule_type:
type: string
enum: ["static", "dynamic"]
description: "Type of schedule. Determines if the schedule is static or dynamic. \n\n**static**: Schedule is fixed and will be used for all recipients. \n\n**dynamic**: Schedule is dynamic and will be computed at runtime using the `dynamic_schedule_expr`."
dynamic_schedule_expr:
type: string
description: "jq-expression for deriving dynamic digest schedule at runtime. Eg. `.digest_schedule`"
example: ".digest_schedule"
schedule:
$ref: '#/components/schemas/Schedule'
retain_count:
type: integer
minimum: 1
maximum: 100
description: "Maximum number of items to retain after digest closes (1-100). By default, 10 items are retained."
retain_order:
type: string
enum: ["first", "last"]
description: "Retain items in this order when retain_count is specified."
trigger_min_count:
type: integer
minimum: 1
description: "Digest will be sent if number of triggers in the batch are greater than or equal to this count, else skipped."
Schedule:
type: object
description: "Static schedule configuration for digest notifications."
properties:
frequency:
type: string
enum: ["minutely", "hourly", "daily", "weekly_mo2fr", "weekly", "monthly"]
description: "Frequency of the digest schedule."
interval:
type: integer
minimum: 1
description: "Multiplier for recurrence schedule. Eg. 2 for every 2 hours, 3 for every 3 days, etc."
weekdays:
type: array
items:
type: string
enum: ["su", "mo", "tu", "we", "th", "fr", "sa"]
description: "Which days to include when frequency is 'weekly'."
monthdays:
type: array
items:
type: object
properties:
pos:
type: integer
minimum: -31
maximum: 31
day:
type: string
enum: [null, "su", "mo", "tu", "we", "th", "fr", "sa"]
description: "Which days to include when frequency is 'monthly'."
time:
type: string
description: "Time of day to send digest in HH:MM format (24-hour)."
examples: ["09:00", "18:30"]
dtstart:
type: string
description: "When to start schedule calculation from in ISO datetime format."
tz_selection:
type: string
enum: ["fixed", "recipient"]
description: "timezone of the recurring schedule. \n\n**fixed**: Fixed timezone. \n\n**recipient**: Recipient's timezone picked from user properties."
tz_fixed:
type: string
description: "Fixed IANA timezone."
pattern: "^[A-Za-z_/]+$"
examples:
new_york:
summary: "New York timezone"
value: "America/New_York"
london:
summary: "London timezone"
value: "Europe/London"
DelayNode:
type: object
description: "[**Delay**](https://docs.suprsend.com/docs/delay): Pauses workflow execution for a specified duration."
required:
- node_type
- name
- delay_type
properties:
name:
type: string
description: Human-readable name of the node
example: "Wait 30 minutes"
description:
type: string
nullable: true
description: Description of what this node does
node_type:
type: string
const: delay
delay_type:
type: string
enum: ["fixed", "dynamic", "relative_to"]
description: "Type of delay. Determines how the duration is calculated. \n\n**Fixed**: Static duration added as XXdXXhXXmXXs.\n\n **Dynamic**: duration is passed as variable in your trigger payload in jq format. Eg. `.delay_duration`, `$recipient.delay_duration`, `$actor.delay_duration`, `$tenant.delay_duration`.\n\n **Relative to**: delay is relative to a future timestamp passed in your trigger payload. Eg. `.start_time` before 15m."
duration:
type: string
description: "Duration value. Required for 'fixed' and 'dynamic' delay types."
examples:
fixed_duration:
summary: "Fixed duration example"
value: "30s"
dynamic_duration:
summary: "Dynamic duration from trigger payload"
value: ".delay_duration"
recipient_duration:
summary: "Dynamic duration from recipient properties"
value: "$recipient.delay_duration"
relative_to:
type: object
description: "Relative delay configuration. Required when delay_type is 'relative_to'."
properties:
pivot_expr:
type: string
description: "(jq-expression) variable defining the future timestamp from trigger payload relative to which delay is calculated."
example: ".start_time"
offset_type:
type: string
enum: ["before", "after"]
description: "Whether offset is to be added or subtracted from pivot_expr."
offset_value_type:
type: string
enum: ["fixed", "dynamic"]
description: "Defines if the offset value is fixed or dynamic. \n\n**Fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. \n\n**Dynamic**: offset is passed as variable in your trigger payload or recipient, tenant properties in jq format. Eg. `$recipient.reminder_offset` before meeting_start_time."
offset_value:
type: string
description: "Offset value"
examples:
fixed_offset:
summary: "Fixed duration offset"
value: "15m"
dynamic_offset:
summary: "Dynamic offset from recipient properties"
value: "$recipient.reminder_offset"
BatchNode:
type: object
description: "[**Batch**](https://docs.suprsend.com/docs/batch): Batches incoming workflow triggers/events for a duration to send consolidated notifications."
required:
- node_type
- name
- mode
- window_type
properties:
name:
type: string
description: Human-readable name of the node
example: "Batch notifications"
description:
type: string
nullable: true
description: Description of what this node does
node_type:
type: string
const: batch
mode:
type: string
enum: ["accumulate_all", "flush_leading_item"]
description: "**accumulate_all**: All events are accumulated in the batch and notification is sent once after batch window closes. \n\n**flush_leading_item**: Notification is sent immediately for the first event in the batch and rest of the events are batched and sent after batch window closes. Eg. Send anomaly alert with first notification sent at the occurrence of first error and next alert sent after 30 minutes if there are further errors."
window_type:
type: string
enum: ["fixed", "dynamic", "relative_to"]
description: "Type of batching window. \n\n**fixed**: Static window duration added as XXdXXhXXmXXs. Eg. 30s, 1h, 1d. \n\n**dynamic**: Batch window duration is passed as variable in your trigger payload. Add the variable in jq format. Eg. `.window_duration`, `$recipient.batch_duration`, `$actor.window_duration`, `$tenant.window_duration`. \n\n**relative_to**: Batch window is relative to a future timestamp passed in your trigger payload. Eg. 15 m before `.task_end_time`."
fixed_window:
type: string
description: "Batch window when window_type is 'fixed'. Static batch window for all users. Format: XXdXXhXXmXXs."
example: "30s"
dynamic_window_expr:
type: string
description: "Batch window when window_type is 'dynamic'. jq-expression for deriving batch window duration at runtime."
examples:
trigger_payload:
summary: "From trigger payload"
value: ".window_duration"
recipient_property:
summary: "From recipient properties"
value: "$recipient.batch_duration"
actor_property:
summary: "From actor properties"
value: "$actor.window_duration"
tenant_property:
summary: "From tenant properties"
value: "$tenant.window_duration"
relative_to:
type: object
description: "Batch window when window_type is 'relative_to'. Batch window is calculated relative to a future timestamp."
properties:
pivot_expr:
type: string
description: "(jq-expression) variable defining the future timestamp from trigger payload relative to which batch window is calculated."
examples:
trigger_payload:
summary: "From trigger payload"
value: ".start_time"
recipient_property:
summary: "From recipient properties"
value: "$recipient.task_end_time"
offset_type:
type: string
enum: ["before", "after"]
description: "Whether offset is to be added or subtracted from pivot timestamp."
offset_value_type:
type: string
enum: ["fixed", "dynamic"]
description: "Defines if the offset value is fixed or dynamic. \n\n**Fixed**: Static duration added as XXdXXhXXmXXs. Eg. 15m before meeting_start_time. \n\n**Dynamic**: offset is passed as variable in your trigger payload or recipient, tenant properties in jq format. Eg. `$recipient.reminder_offset` before meeting_start_time."
offset_value:
type: string
description: "Offset value."
examples:
fixed_offset:
summary: "Fixed duration offset"
value: "15m"
dynamic_offset:
summary: "Dynamic offset from recipient properties"
value: "$recipient.reminder_offset"
retain_count:
type: integer
minimum: 1
maximum: 100
description: "Maximum number of items to retain after batch closes (1-100). The output variable set will have the latest or first n items based on the retain_order."
retain_order:
type: string
enum: ["first", "last"]
# --- truncated at 32 KB (709 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-rest-api-openapi.yml