POST
/
v1
/
{workspace}
/
workflow
/
{slug}
/
cURL
curl -X POST "https://api.suprsend.com/v1/{workspace}/workflow/{slug}/" \
  --header 'Authorization: ServiceToken <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Welcome Email",
    "description": "Sends welcome email to new users",
    "category": "transactional",
    "tags": ["welcome", "onboarding"],
    "tree": {
      "nodes": [
        {
          "name": "Send Email",
          "node_type": "send_email",
          "properties": {
            "template": "welcome-email-template",
            "subject": "Welcome to our platform!"
          },
          "description": "Send welcome email to new users"
        }
      ]
    }
  }'
{
  "validation_result": {
    "is_valid": true,
    "errors": [
      "<string>"
    ]
  }
}
Create a new workflow or update an existing workflow configuration. You can optionally commit the workflow immediately upon creation/update.

Authorizations

​
ServiceToken <token>
string
header
required

You can get Service Token from SuprSend dashboard -> Account Settings -> Service Tokens section.

Path Parameters

​
workspace
string
required

Workspace where the workflow should be created (staging, production, etc.)

​
slug
string
required

Unique identifier of the workflow. You can get it from workflow settings for existing workflows.

Query Parameters

​
commit
boolean
default:false

Whether to commit the workflow immediately. Workflow will be successfully committed only if validation_result.is_valid is true.

​
commit_message
string

Commit message describing the changes (required if commit=true)

Body

application/json
​
name
string
required

Human-readable name of the workflow. Workflow slug is generated from this name for new workflows.

Example:

"Welcome Sequence"

​
category
string
required

Notification category of the workflow. Used to apply category-specific settings and preferences.

Example:

"transactional"

​
trigger_type
enum<string>
required

You can trigger a workflow either via API by passing its slug directly, or through an event-based system where the workflow runs when a specific event occurs. You can compare both methods here. If the workflow should run when a user enters or exits a list, use trigger_type = event.

Available options:
event,
api
​
tree
object
required

Node tree structure of the workflow. Contains the nodes array with all workflow nodes and their configuration.

​
description
string | null

Description explaining the usecase of the workflow

​
is_enabled
boolean
default:true

Whether the workflow should be enabled

​
tags
string[]

Tags are used for grouping and filtering workflows in list.

Example:
["onboarding-sequence"]
​
payload_schema
object | null

Schema to validate workflow api data structure. Used only when trigger_type = api.

​
trigger_events
string[]

Events that trigger this workflow (required if trigger_type = event). In case of list entry/exit, event names will be $USER_ENTERED_LIST - <list_id> and $USER_EXITED_LIST - <list_id> respectively.

​
ratelimit
object | null

Throttle settings for the workflow. This is used to limit the number of times a workflow can be executed per user in a given time period.

​
conditions
object[] | null

Trigger Conditions. Workflow will be executed if any of the conditions in this array evaluate to true.

​
override_recipients_type
enum<string>

Override recipients using a property from the trigger payload. Type defines if the workflow should run for a list of users or a single object. Only applicable for trigger_type = event.

Available options:
user,
single_object_fields
Example:

"user"

​
override_recipients_user_expr
string | null

JQ expression to override recipients when override_recipients_type = user. Only applicable for trigger_type = event.

Example:

".distinct_id"

​
override_recipients_single_object_fields_expr
object | null

JQ expression to override recipients with object when override_recipients_type = single_object_fields. Only applicable for trigger_type = event.

Example:
{
  "id": ".object_id",
  "object_type": ".object_type",
  "$object_subscriptions_query.depth": "2"
}
​
override_actor_user_expr
string | null

JQ expression to override actor. Only applicable for trigger_type = event.

Example:

".actor_id"

​
override_tenant_expr
string | null

JQ expression to override tenant. Only applicable for trigger_type = event.

Example:

".tenant_id"

Response

The response includes the same workflow object as input along with a validation_result field that indicates whether the workflow configuration is valid.

​
validation_result
object