Create or Update Variant

POST

{workspace}

template

{template_slug}

channel

{channel}

variant

{variant_id}

Upsert Variant

curl -X POST "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/" \
  --header 'Authorization: ServiceToken <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "locale": "en",
    "tenant_id": null,
    "conditions": [],
    "content": { ... }
  }'

import requests

url = "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/"

payload = {
    "locale": "en",
    "tenant_id": "<string>",
    "conditions": [
        {
            "type": "expression_v1",
            "expression_v1": {
                "op": "AND",
                "args": [
                    {
                        "variable": "<string>",
                        "value": "<string>"
                    }
                ]
            }
        }
    ],
    "content": {},
    "needs_vendor_approval": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locale: 'en',
    tenant_id: '<string>',
    conditions: [
      {
        type: 'expression_v1',
        expression_v1: {op: 'AND', args: [{variable: '<string>', value: '<string>'}]}
      }
    ],
    content: {},
    needs_vendor_approval: true
  })
};

fetch('https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'locale' => 'en',
    'tenant_id' => '<string>',
    'conditions' => [
        [
                'type' => 'expression_v1',
                'expression_v1' => [
                                'op' => 'AND',
                                'args' => [
                                                                [
                                                                                                                                'variable' => '<string>',
                                                                                                                                'value' => '<string>'
                                                                ]
                                ]
                ]
        ]
    ],
    'content' => [
        
    ],
    'needs_vendor_approval' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/"

	payload := strings.NewReader("{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}"

response = http.request(request)
puts response.read_body

{
  "$schema": "https://schema.suprsend.com/template/v2/variant_schema.json",
  "channel": "email",
  "id": "default",
  "tenant_id": null,
  "locale": "en",
  "conditions": [],
  "hash": "97f031b56ba642d137758652ce21dda6962ecee81d544fcf245661898107bcb9",
  "needs_vendor_approval": false,
  "sysgen_template_name": null,
  "approval_status": "auto_approved",
  "discard_comment": null,
  "approval_at": "2026-04-07T10:39:28.502737Z",
  "content": {
    "$schema": "https://schema.suprsend.com/template/v2/channel/email_schema.json",
    "templating_language": "handlebars",
    "from_name": "Acme Store",
    "from_address": "noreply@acme-store.com",
    "extra_to": "",
    "cc": "",
    "bcc": "",
    "reply_to": "",
    "subject": "Your order has been shipped - #{{order.number}}",
    "body": {
      "type": "raw",
      "raw": {
        "html": "<html><body><h1>Order Shipped!</h1><p>Hi {{customer.name}},</p><p>Your order <strong>#{{order.number}}</strong> has been shipped and is on its way.</p><p>Expected delivery: {{order.delivery_date}}</p><p><a href=\"{{{order.tracking_url}}}\">Track your order</a></p></body></html>",
        "text": "Hi {{customer.name}}, Your order #{{order.number}} has been shipped. Expected delivery: {{order.delivery_date}}. Track: {{{order.tracking_url}}}"
      },
      "designer": {
        "html": "...",
        "text": "...",
        "design_json": {},
        "merge_tags": [],
        "display_conditions": []
      },
      "preheader": "Your order #{{order.number}} is on its way",
      "plain_text": null,
      "email_markup": ""
    }
  },
  "errors": {},
  "vendor_approvals": [],
  "has_error": false,
  "seq_no": 1,
  "action": null,
  "created_at": "2026-04-07T10:39:28.510000Z"
}

{
  "$schema": "https://schema.suprsend.com/template/v2/variant_schema.json",
  "channel": "email",
  "id": "default",
  "tenant_id": "<string>",
  "locale": "en",
  "conditions": [
    {}
  ],
  "hash": "<string>",
  "needs_vendor_approval": true,
  "sysgen_template_name": "<string>",
  "approval_status": "auto_approved",
  "discard_comment": "<string>",
  "approval_at": "2023-11-07T05:31:56Z",
  "has_error": true,
  "seq_no": 123,
  "action": "added",
  "created_at": "2023-11-07T05:31:56Z",
  "content": {},
  "vendor_approvals": [
    {}
  ]
}

{
  "code": 401,
  "error_code": "authentication_failed",
  "type": "AuthenticationFailed",
  "message": "Invalid service token.",
  "detail": "Invalid service token."
}

{
  "code": 404,
  "error_code": "not_found",
  "type": "NotFound",
  "message": "workspace 'demo' not found",
  "detail": "workspace 'demo' not found"
}

Authorizations

Authorization

string

header

required

Pass as Authorization: ServiceToken <token>. You can get Service Token from SuprSend dashboard -> Account Settings -> Service Tokens section.

Path Parameters

workspace

string

required

template_slug

string

required

channel

enum<string>

required

Available options:

email,

sms,

whatsapp,

inbox,

androidpush,

iospush,

webpush,

slack,

ms_teams

variant_id

string

required

Variant identifier. If a variant with this ID doesn't exist, a new one is created.

Body

application/json

locale

string

required

Locale code for the variant (e.g., en, es, fr). Must be a supported locale code.

Example:

"en"

tenant_id

string | null

Tenant ID this variant is scoped to. null for the default variant.

conditions

object[]

Conditions for variant selection. Structure follows the expression format.

Show child attributes

content

object

Channel-specific content. See variant content schema for the structure of each channel.

needs_vendor_approval

boolean

(SMS only) Whether this variant requires vendor (DLT) approval. Ignored for other channels: WhatsApp variants always require approval, and all other channels never do.

Response

Variant created successfully. Returns the full variant including its content.

$schema

string

Schema URL for variant validation.

Example:

"https://schema.suprsend.com/template/v2/variant_schema.json"

channel

string

Channel this variant belongs to.

Example:

"email"

string

Variant identifier.

Example:

"default"

tenant_id

string | null

Tenant this variant is scoped to, or null for default.

locale

string

Locale code.

Example:

"en"

conditions

object[]

Conditions for variant selection at send time.

hash

string

Content hash for change detection.

needs_vendor_approval

boolean

Whether this variant requires vendor approval (SMS DLT, WhatsApp).

sysgen_template_name

string | null

System-generated template name for vendor approval.

approval_status

enum<string>

Current approval status of the variant.

Available options:

auto_approved,

pending,

sent_for_approval,

approved,

rejected,

discarded,

upload_failed

discard_comment

string | null

Reason provided when a variant is discarded.

approval_at

string<date-time> | null

Timestamp when the variant was approved.

has_error

boolean

Whether the variant has validation errors.

seq_no

integer

Ordering within the channel + tenant + locale combination.

action

enum<string> | null

Action taken in the latest commit (added, updated, unchanged, deleted, or null in draft).

Available options:

added,

updated,

unchanged,

deleted

created_at

string<date-time>

Timestamp when the variant was created.

content

object

Channel-specific content. Structure varies by channel. Returned by the variant detail endpoint, and by the variant list endpoints only when include_content=true is passed.

vendor_approvals

object[]

Vendor approval entries (WhatsApp/SMS only). Returned by the variant detail endpoint, and by the variant list endpoints only when include_content=true is passed.

⌘I

Upsert Variant

curl -X POST "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/" \
  --header 'Authorization: ServiceToken <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "locale": "en",
    "tenant_id": null,
    "conditions": [],
    "content": { ... }
  }'

import requests

url = "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/"

payload = {
    "locale": "en",
    "tenant_id": "<string>",
    "conditions": [
        {
            "type": "expression_v1",
            "expression_v1": {
                "op": "AND",
                "args": [
                    {
                        "variable": "<string>",
                        "value": "<string>"
                    }
                ]
            }
        }
    ],
    "content": {},
    "needs_vendor_approval": True
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locale: 'en',
    tenant_id: '<string>',
    conditions: [
      {
        type: 'expression_v1',
        expression_v1: {op: 'AND', args: [{variable: '<string>', value: '<string>'}]}
      }
    ],
    content: {},
    needs_vendor_approval: true
  })
};

fetch('https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'locale' => 'en',
    'tenant_id' => '<string>',
    'conditions' => [
        [
                'type' => 'expression_v1',
                'expression_v1' => [
                                'op' => 'AND',
                                'args' => [
                                                                [
                                                                                                                                'variable' => '<string>',
                                                                                                                                'value' => '<string>'
                                                                ]
                                ]
                ]
        ]
    ],
    'content' => [
        
    ],
    'needs_vendor_approval' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/"

	payload := strings.NewReader("{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"locale\": \"en\",\n  \"tenant_id\": \"<string>\",\n  \"conditions\": [\n    {\n      \"type\": \"expression_v1\",\n      \"expression_v1\": {\n        \"op\": \"AND\",\n        \"args\": [\n          {\n            \"variable\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    }\n  ],\n  \"content\": {},\n  \"needs_vendor_approval\": true\n}"

response = http.request(request)
puts response.read_body

{
  "$schema": "https://schema.suprsend.com/template/v2/variant_schema.json",
  "channel": "email",
  "id": "default",
  "tenant_id": null,
  "locale": "en",
  "conditions": [],
  "hash": "97f031b56ba642d137758652ce21dda6962ecee81d544fcf245661898107bcb9",
  "needs_vendor_approval": false,
  "sysgen_template_name": null,
  "approval_status": "auto_approved",
  "discard_comment": null,
  "approval_at": "2026-04-07T10:39:28.502737Z",
  "content": {
    "$schema": "https://schema.suprsend.com/template/v2/channel/email_schema.json",
    "templating_language": "handlebars",
    "from_name": "Acme Store",
    "from_address": "noreply@acme-store.com",
    "extra_to": "",
    "cc": "",
    "bcc": "",
    "reply_to": "",
    "subject": "Your order has been shipped - #{{order.number}}",
    "body": {
      "type": "raw",
      "raw": {
        "html": "<html><body><h1>Order Shipped!</h1><p>Hi {{customer.name}},</p><p>Your order <strong>#{{order.number}}</strong> has been shipped and is on its way.</p><p>Expected delivery: {{order.delivery_date}}</p><p><a href=\"{{{order.tracking_url}}}\">Track your order</a></p></body></html>",
        "text": "Hi {{customer.name}}, Your order #{{order.number}} has been shipped. Expected delivery: {{order.delivery_date}}. Track: {{{order.tracking_url}}}"
      },
      "designer": {
        "html": "...",
        "text": "...",
        "design_json": {},
        "merge_tags": [],
        "display_conditions": []
      },
      "preheader": "Your order #{{order.number}} is on its way",
      "plain_text": null,
      "email_markup": ""
    }
  },
  "errors": {},
  "vendor_approvals": [],
  "has_error": false,
  "seq_no": 1,
  "action": null,
  "created_at": "2026-04-07T10:39:28.510000Z"
}

{
  "$schema": "https://schema.suprsend.com/template/v2/variant_schema.json",
  "channel": "email",
  "id": "default",
  "tenant_id": "<string>",
  "locale": "en",
  "conditions": [
    {}
  ],
  "hash": "<string>",
  "needs_vendor_approval": true,
  "sysgen_template_name": "<string>",
  "approval_status": "auto_approved",
  "discard_comment": "<string>",
  "approval_at": "2023-11-07T05:31:56Z",
  "has_error": true,
  "seq_no": 123,
  "action": "added",
  "created_at": "2023-11-07T05:31:56Z",
  "content": {},
  "vendor_approvals": [
    {}
  ]
}

{
  "code": 401,
  "error_code": "authentication_failed",
  "type": "AuthenticationFailed",
  "message": "Invalid service token.",
  "detail": "Invalid service token."
}

{
  "code": 404,
  "error_code": "not_found",
  "type": "NotFound",
  "message": "workspace 'demo' not found",
  "detail": "workspace 'demo' not found"
}

API Reference

WORKSPACE & AUTH KEYS

WORKFLOWS

SCHEMAS

EVENTS

CATEGORIES

TRANSLATIONS

TEMPLATES

Authorizations

Path Parameters

Body

Response