Skip to main content
Categories are assigned to workflows and are used to manage notification preferences in SuprSend. For detailed concepts, see Notification Categories.

​
Creating sections and sub-categories

Go to Developers → Notification categories and select a root-category (System, Transactional, or Promotional).
  • 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

Sections are optional and help organize sub-categories on the preference page. To create a section:
  1. Click +Section
  2. Add name and description for the section
  3. Click Save Changes
You’ll see the updated section inside the category and can edit it later by clicking on the Edit button against that section.

​
Adding sub-categories

To add a sub-category:
  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.
Don’t change the sub-category name after using it in workflows—it updates the slug and can break existing workflows.

​
Configuring default preferences

Select a sub-category and choose a default preference: On, Off, or Can’t Unsubscribe. This determines the default behavior for users who haven’t set their own preference.

​
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.
These defaults are recommendations—adjust them based on your product’s requirements and user expectations. System
  • 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.
Transactional
  • 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.
Promotional
  • Default: ON — Users receive notifications by default. For optional categories, set to OFF so users only receive notifications if they explicitly opt in

​
Adding tags (Optional)

Tags are used to filter categories on the preference page. Common usecases are to filter categories based on user role or department. They can be added to sections and sub-categories.
  1. Select a section or sub-category
  2. Add tags (e.g., finance, manager)
  3. Section-level tags apply to all sub-categories in that section

Tags within preference categories

You can filter categories using the tags query parameter in the get user preference API.
Tags do not impact delivery logic or preference rules — they are only used for filtering and organizing the UI. Even if a category is hidden from the user on the preference page due to tag filters, the user can still opt in/out via API, and notifications will still be sent if the default preference is set to opt-in.

​
Preview and publish

Before making your categories live, preview how they’ll appear to users, then publish your changes. Category changes are version controlled and are not live until you publish them. This is done to ensure that your users do not see intermittent changes when they are interacting with the preference page.
1

Preview

Click Preview to see how categories will appear to users on the preference page.The preview will show how your categories are organized and displayed to users.
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.
Category changes are version controlled and need to be publishedCategories will only appear in workflow dropdowns after they are published. If you don’t see your category in the dropdown, make sure you’ve published your changes.

​
Assigning category to workflows

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

Assigning category to workflows

​
Managing category translations

This feature is only available for Enterprise plan customers or the ones who have enabled translation feature in their account.
Upload and manage translations for category and section names and descriptions. Once uploaded, translations go live immediately. You can fetch preference translations by passing locale query parameter in the get user preference API.

For more details on what it does and how it works, see Overview of category translations.
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 (e.g., 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.
{
  "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
    }
  }
}
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.

Embeddable preference page preview

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.

​
Frequently Asked Questions

Create sections when:
  • Large number of categories: If you have 10+ sub-categories, sections help users navigate the preference page more easily
  • Similar categories: Group related sub-categories together (e.g., “Billing” section for invoice, payment, and subscription categories)
  • Better organization: Sections improve the user experience by organizing categories into logical groups
Example: If you have categories like “Invoice Ready”, “Payment Reminder”, and “Subscription Renewal”, group them under a “Billing” section for better organization.
Keep your category structure simple and focused on the most important notification types. Here are some guidelines:
  • Recommended: 5-8 sub-categories or 5-8 sections and within each section, 2-6 sub-categories. Try to keep total number of categories across all root-categories < 20.
  • Too many categories can overwhelm users and drive them to use channel-level opt-outs instead
  • Too few categories may not give users enough granular control
Best practice: Create categories based on user actions or notification flows (e.g., “Order Updates”, “Account Security”, “Marketing Newsletters”) rather than creating a category for every single workflow.
This typically happens when you’re using root-categories instead of sub-categories in your workflows.User Preferences do not apply to root-categories (System, Transactional, Promotional). If you’re sending notifications with notification_category: "promotional" or notification_category: "transactional", users will continue to receive notifications even after opting out of all sub-categories.To fix this:
  1. Check your workflow settings and ensure you’re using sub-category slugs (e.g., "marketing", "order-updates") instead of root-category names
  2. If you don’t see the sub-categories in dropdown, it is possible that the sub-categories are not published. Category changes are version controlled and are not live until you publish them.
Use tags to filter categories based on user roles, departments, or teams. Tags allow you to customize which categories appear on each user’s preference page.How it works:
  1. Add tags to sections or sub-categories from the Preference categories page
  2. When fetching user preferences via API, pass the tags query parameter to filter categories
  3. Only categories matching the specified tags will be returned
Important: Tags only affect what’s shown on the preference page—they don’t impact delivery logic. Users can still opt in/out, and notifications will be sent based on default preferences if the category is hidden from the UI.Read more about tags here.