Manage Categories and Preferences

​

Creating sections and sub-categories

• System is for critical account related notifications that users can’t unsubscribe from.
• Transactional is for notifications sent in response to user actions or transactions.
• Promotional is for marketing notifications sent to promote products or re-engage users to your platform.

​

Creating a section

1. Click +Section
2. Add name and description for the section
3. Click Save Changes

​

Adding sub-categories

1. Click +Sub-Category
2. Fill in:
   • Name: What users see (slug (assigned to workflow) will be auto-generated from name)
   • Section: Select the section where this sub-category will be grouped. Leave blank if you don’t want to group it under any section.
   • Description (Optional): Description is used to describe the kind of notifications sent in the category. Helps users get more context about the category.

​

Configuring default preferences

​

Preference types

• On: Users receive notifications by default (they can opt out)
• Off: Users don’t receive notifications by default (they can opt in)
• Can’t Unsubscribe: Users cannot fully opt out of these notifications (typically for critical system messages). Users can still opt out of specific channels, but at least one mandatory channel must remain active.

​

Recommended defaults by category type

• Default: Can't Unsubscribe - Set the channel most users have on as mandatory so they don’t miss critical notifications even if they opt out of all channels.

• Default: Can't Unsubscribe - These are notifications sent in response to user actions or transactions. You would generally not want users to opt out of these notifications. However, you can adjust the default preference based on the criticality of the notification.

• Default: ON - Users receive notifications by default. For optional categories, set to OFF so users only receive notifications if they explicitly opt in

​

Configuring digest schedule

1. Select a sub-category and enable Digest schedule.
2. Add one or more options. For each option, set:
   • Label — what the user sees in the preference center (for example, “Daily”).
   • Frequency — instantly, hourly, daily, weekly, or monthly.
   • Interval — recurrence multiplier (for example, interval =2 with weekly frequency means every 2 weeks).
   • Time / weekdays / month days — when to send, depending on frequency. Each of these has an edit policy:
     • Editable — the user can change the value in the preference center; the value you set is the default.
     • Locked — the value is fixed and the user can’t change it.
3. Mark exactly one option as the default (used when a user hasn’t chosen one).

​

Configuring condition properties

1. Select a sub-category and add a condition property (up to 25 per sub-category). For each property, set:
   • Key — unique identifier used in workflows. Referenced as $category.properties.<key>.
   • Label — display label shown in the preference center.
   • Value type — integer, string, string_choice (single-select), list_choice (multi-select), string_dynamic, or list_dynamic.
   • Choices — for string_choice / list_choice, the selectable options (label shown to the user, value used in the workflow).
   • Default value — applied when no value is set. You can set a property optional to skip adding default value.
   • Edit policy or is_user_editable — selected or editable means user can change it or unselected/locked means fixed.
   • is_optional - you can mark the property as optional if it can have null default value.
2. Reference the property inside a workflow branch condition as $category.properties.<key>.

$recipient.subscription.role == $category.properties.role

• Send anomaly alerts only when an error rate crosses a user-defined threshold.
• Deliver alerts only at or above a user-selected severity (for example, High).
• Let admins choose which user roles receive a category’s notifications.

​

Adding tags (Optional)

1. Select a section or sub-category
2. Add tags (for example, finance, manager)
3. Section-level tags apply to all sub-categories in that section

​

Preview and publish

1

Preview

Click Preview to see how categories will appear to users on the preference page. The preview renders the full preference experience, including:

• Default preferences — on/off toggle and can’t-unsubscribe states
• Channel preferences — which channels are shown as opted in or mandatory
• Digest schedule — the cadence options users can choose from
• Condition properties — user-editable fields like thresholds or severity selectors

Use the preview to verify that all your preference settings are configured correctly before publishing.

2

Publish

Click Publish Changes to make categories live. Categories are only available in workflows after publishing and will not appear in workflow dropdowns until published.

3

Clone to production

Use Clone to copy changes from staging to production workspace. Not required if you are directly doing changes in production workspace. Clone option is not currently available on UI.

​

Assigning category to workflows

• Via Dashboard
• in dynamic workflow API
• Via CLI or Management API

In workflow editor, select any delivery node and choose the relevant category from the Preference Category dropdown.

Add the category slug to the notification_category field in your dynamic workflow trigger.To find the slug: Click the sub-category name in the categories page to copy it.

Example:

python

from suprsend import Suprsend, Workflow

supr_client = Suprsend("_workspace_key_", "_workspace_secret_")

workflow_body = {
  "name": "welcome-email",
  "template": "template_slug",
  "notification_category": "newsletter",  # sub-category slug
  "users": [
    {
      "distinct_id": "user-123"
    }
  ]
}

wf = Workflow(body=workflow_body)
response = supr_client.trigger_workflow(wf)
print(response)

Checkout complete API reference.

Pass category-slug to category field in workflow payload while updating workflow through management API or CLI.

​

Managing category translations

• Via Dashboard
• Via Management API
• Via CLI

1

Click translation icon

On the Preference categories page, click the translation icon in the top right corner to open the “Add / View Translation files” modal.

2

Add translation file

Click ”+ Add Translation”. Select a locale and upload the translated JSON file (for example, es.json, fr.json), then click “Save & Add”.

Translation file structure:Translation files follow this JSON structure with sections and categories objects. Each section and category is identified by its slug.

file-structure

example

{
  "sections": {
    "section-slug": {
      "name": "Translated section name",
      "description": "Translated section description" // or null
    }
  },
  "categories": {
    "category-slug": {
      "name": "Translated category name",
      "description": "Translated category description" // or null
    }
  }
}

{
  "sections": {
    "billing": {
      "name": "Facturation",
      "description": "Notifications liées à la facturation"
    }
  },
  "categories": {
    "invoice-ready": {
      "name": "Facture prête",
      "description": "Vous recevrez une notification lorsque votre facture est prête"
    },
    "payment-reminder": {
      "name": "Rappel de paiement",
      "description": null
    }
  }
}

Note: The en.json file is automatically generated from your preference settings. Download it to use as a template for translations.

3

Preview translations

Click the Preview button (next to the translations button) on the Preference categories page to see how if your preview is rendering correctly in different languages.

4

Clone to production

Use CLI command suprsend category translation pull and CLI command suprsend category translation push to copy translations from staging to production workspace.

suprsend category translation pull
suprsend category translation push --workspace production

English (en.json) is automatically created and cannot be overridden. It serves as the base language for all translations.

Use Management API to programmatically add, update, or delete translations for specific locales.See Category Translation API for complete API reference.

See CLI Category Translation documentation for category translation pull and category translation push commands.

​

Frequently Asked Questions

​

Related documentation

• Preference Categories - Concepts and detailed explanations of preference categories
• User Preferences - Overview of how users can set their Preferences
• Tenant Preferences - How to apply admin-level preference settings to all users belonging to a tenant
• Preference Evaluation - How SuprSend evaluates preferences at runtime