Category and Channel within Category

PATCH

user

{distinct_id}

preference

category

{category_slug}

Update User Category Preference - Opt Out Channel

curl -X PATCH "https://hub.suprsend.com/v1/user/user123/preference/status-update-alert/" \
  --header 'Authorization: Bearer __YOUR_API_KEY__' \
  --header 'Content-Type: application/json' \
  --data '{
    "preference": "opt_in",
    "opt_out_channels": ["email", "slack"]
  }'

import requests

url = "https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/"

payload = {
    "preference": "opt_in",
    "opt_out_channels": ["<string>"],
    "opt_in_channels": ["<string>"],
    "digest_schedule": {
        "id": "<string>",
        "time": "<string>",
        "dtstart": "2023-11-07T05:31:56Z",
        "weekdays": [],
        "monthdays": [
            {
                "pos": 123,
                "day": "<string>"
            }
        ]
    },
    "properties": [
        {
            "key": "<string>",
            "value": "<unknown>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    preference: 'opt_in',
    opt_out_channels: ['<string>'],
    opt_in_channels: ['<string>'],
    digest_schedule: {
      id: '<string>',
      time: '<string>',
      dtstart: '2023-11-07T05:31:56Z',
      weekdays: [],
      monthdays: [{pos: 123, day: '<string>'}]
    },
    properties: [{key: '<string>', value: '<unknown>'}]
  })
};

fetch('https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/', 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://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'preference' => 'opt_in',
    'opt_out_channels' => [
        '<string>'
    ],
    'opt_in_channels' => [
        '<string>'
    ],
    'digest_schedule' => [
        'id' => '<string>',
        'time' => '<string>',
        'dtstart' => '2023-11-07T05:31:56Z',
        'weekdays' => [
                
        ],
        'monthdays' => [
                [
                                'pos' => 123,
                                'day' => '<string>'
                ]
        ]
    ],
    'properties' => [
        [
                'key' => '<string>',
                'value' => '<unknown>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/"

	payload := strings.NewReader("{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.patch("https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}"

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

{
  "name": "Weekly Activity Digest",
  "category": "weekly-activity-digest",
  "description": "Summary of recent activity in your workspace",
  "tags": [
    "digest",
    "activity"
  ],
  "effective_tags": [
    "digest",
    "activity"
  ],
  "original_preference": "opt_in",
  "preference": "opt_in",
  "is_editable": true,
  "channels": [
    {
      "channel": "email",
      "preference": "opt_in",
      "is_editable": true
    }
  ],
  "digest_schedule_options": {
    "options": [
      {
        "id": "instant",
        "label": "Instant",
        "frequency": "instantly",
        "is_default": false,
        "is_user_selected": false
      },
      {
        "id": "daily-summary",
        "label": "Daily summary at 9:00 AM",
        "frequency": "daily",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00",
          "value": ""
        },
        "is_default": true,
        "is_user_selected": false
      },
      {
        "id": "weekly-on-weekdays",
        "label": "Every week on Mon–Fri · time set by recipient (default: 9:00 AM)",
        "frequency": "weekly_mo2fr",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00",
          "value": "10:00"
        },
        "weekdays": {
          "edit_policy": "locked",
          "default_value": [
            "mo",
            "tu",
            "we",
            "th",
            "fr"
          ],
          "value": [
            "mo",
            "tu",
            "we",
            "th",
            "fr"
          ]
        },
        "is_default": false,
        "is_user_selected": true
      }
    ]
  },
  "digest_schedule": {
    "id": "weekly-on-weekdays",
    "label": "Every week on Mon–Fri · time set by recipient (default: 9:00 AM)",
    "frequency": "weekly_mo2fr",
    "interval": 1,
    "time": "10:00",
    "weekdays": [
      "mo",
      "tu",
      "we",
      "th",
      "fr"
    ],
    "is_default": false,
    "is_user_selected": true
  },
  "properties": [
    {
      "key": "threshold",
      "label": "Minimum activity count",
      "value_type": "string",
      "default_value": "100",
      "is_optional": false,
      "edit_policy": "editable",
      "is_overridden": true,
      "value": "500"
    }
  ]
}

{
  "code": 404,
  "message": "category '_category_slug_' not found"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

distinct_id

string

required

distinct_id of the user whose preferences should be fetched

category_slug

string

required

notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page

Query Parameters

tenant_id

string

to fetch user preferences for a particular tenant

locale

string

Locale code (e.g., es, fr, de, ja, es-AR) to fetch translated category and section names and descriptions. When provided, the API returns category and section names and descriptions in the specified language if translations are available. If a translation is missing for the requested locale, the system automatically falls back in this order: locale-region (e.g., es-AR) → locale (e.g., es) → en (English - always available).

Body

application/json

preference

string

default:opt_in

choose one of the options: opt_in if the user has allowed notification in this category and opt_out if user wants to discontinue notification in this category

opt_out_channels

string[]

Add array of channels if user wants to unsubscribe from particular channels in this category. Add channels as email, sms, whatsapp, androidpush, inbox, iospush, slack, webpush

opt_in_channels

string[]

You can either pass opt_out_channels when user opts out from a channel in the category or opt_in_channels when user opts in to a channel in the category. Add channels as email, sms, whatsapp, androidpush, inbox, iospush, slack, webpush

digest_schedule

object | null

User's preferred digest schedule for this category. Set to null to fall back to tenant's default.

Show child attributes

properties

object[]

Override values for category condition properties. Only properties with edit_policy editable can be overridden. The datatype of value must match the property's value_type.

Show child attributes

Response

202

name

string

Display name of the notification category.

Example:

"Weekly Activity Digest"

tags

string[] | null

effective_tags

string[] | null

original_preference

string

default preference of the category

Example:

"opt_in"

preference

string

final user preference of the category

Example:

"opt_in"

is_editable

boolean

false for categories where default preference is set to can't unsubscribe

Example:

true

channels

object[]

Show child attributes

digest_schedule_options

object | null

All available digest schedule options for this category, showing user selections

Show child attributes

digest_schedule

object | null

The user's currently active digest schedule selection

Show child attributes

properties

object[] | null

Category condition properties with user overrides

Show child attributes

Overall Channel levelAPI to update user preferences across all channels.

⌘I

Update User Category Preference - Opt Out Channel

curl -X PATCH "https://hub.suprsend.com/v1/user/user123/preference/status-update-alert/" \
  --header 'Authorization: Bearer __YOUR_API_KEY__' \
  --header 'Content-Type: application/json' \
  --data '{
    "preference": "opt_in",
    "opt_out_channels": ["email", "slack"]
  }'

import requests

url = "https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/"

payload = {
    "preference": "opt_in",
    "opt_out_channels": ["<string>"],
    "opt_in_channels": ["<string>"],
    "digest_schedule": {
        "id": "<string>",
        "time": "<string>",
        "dtstart": "2023-11-07T05:31:56Z",
        "weekdays": [],
        "monthdays": [
            {
                "pos": 123,
                "day": "<string>"
            }
        ]
    },
    "properties": [
        {
            "key": "<string>",
            "value": "<unknown>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    preference: 'opt_in',
    opt_out_channels: ['<string>'],
    opt_in_channels: ['<string>'],
    digest_schedule: {
      id: '<string>',
      time: '<string>',
      dtstart: '2023-11-07T05:31:56Z',
      weekdays: [],
      monthdays: [{pos: 123, day: '<string>'}]
    },
    properties: [{key: '<string>', value: '<unknown>'}]
  })
};

fetch('https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/', 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://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'preference' => 'opt_in',
    'opt_out_channels' => [
        '<string>'
    ],
    'opt_in_channels' => [
        '<string>'
    ],
    'digest_schedule' => [
        'id' => '<string>',
        'time' => '<string>',
        'dtstart' => '2023-11-07T05:31:56Z',
        'weekdays' => [
                
        ],
        'monthdays' => [
                [
                                'pos' => 123,
                                'day' => '<string>'
                ]
        ]
    ],
    'properties' => [
        [
                'key' => '<string>',
                'value' => '<unknown>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/"

	payload := strings.NewReader("{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.patch("https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hub.suprsend.com/v1/user/{distinct_id}/preference/category/{category_slug}/")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"preference\": \"opt_in\",\n  \"opt_out_channels\": [\n    \"<string>\"\n  ],\n  \"opt_in_channels\": [\n    \"<string>\"\n  ],\n  \"digest_schedule\": {\n    \"id\": \"<string>\",\n    \"time\": \"<string>\",\n    \"dtstart\": \"2023-11-07T05:31:56Z\",\n    \"weekdays\": [],\n    \"monthdays\": [\n      {\n        \"pos\": 123,\n        \"day\": \"<string>\"\n      }\n    ]\n  },\n  \"properties\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": \"<unknown>\"\n    }\n  ]\n}"

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

{
  "name": "Weekly Activity Digest",
  "category": "weekly-activity-digest",
  "description": "Summary of recent activity in your workspace",
  "tags": [
    "digest",
    "activity"
  ],
  "effective_tags": [
    "digest",
    "activity"
  ],
  "original_preference": "opt_in",
  "preference": "opt_in",
  "is_editable": true,
  "channels": [
    {
      "channel": "email",
      "preference": "opt_in",
      "is_editable": true
    }
  ],
  "digest_schedule_options": {
    "options": [
      {
        "id": "instant",
        "label": "Instant",
        "frequency": "instantly",
        "is_default": false,
        "is_user_selected": false
      },
      {
        "id": "daily-summary",
        "label": "Daily summary at 9:00 AM",
        "frequency": "daily",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00",
          "value": ""
        },
        "is_default": true,
        "is_user_selected": false
      },
      {
        "id": "weekly-on-weekdays",
        "label": "Every week on Mon–Fri · time set by recipient (default: 9:00 AM)",
        "frequency": "weekly_mo2fr",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00",
          "value": "10:00"
        },
        "weekdays": {
          "edit_policy": "locked",
          "default_value": [
            "mo",
            "tu",
            "we",
            "th",
            "fr"
          ],
          "value": [
            "mo",
            "tu",
            "we",
            "th",
            "fr"
          ]
        },
        "is_default": false,
        "is_user_selected": true
      }
    ]
  },
  "digest_schedule": {
    "id": "weekly-on-weekdays",
    "label": "Every week on Mon–Fri · time set by recipient (default: 9:00 AM)",
    "frequency": "weekly_mo2fr",
    "interval": 1,
    "time": "10:00",
    "weekdays": [
      "mo",
      "tu",
      "we",
      "th",
      "fr"
    ],
    "is_default": false,
    "is_user_selected": true
  },
  "properties": [
    {
      "key": "threshold",
      "label": "Minimum activity count",
      "value_type": "string",
      "default_value": "100",
      "is_optional": false,
      "edit_policy": "editable",
      "is_overridden": true,
      "value": "500"
    }
  ]
}

{
  "code": 404,
  "message": "category '_category_slug_' not found"
}

API Reference

USERS

TRIGGER WORKFLOWS

EVENTS

MESSAGES

OBJECTS

TEMPLATES

TENANTS

PREFERENCE

LISTS

BROADCAST

Authorizations

Path Parameters

Query Parameters

Body

Response