Skip to main content
Notification categories define the classification your workflow belongs to. Each workflow can be either to a root-category (system, transactional, or promotional) or a sub-category. User Preference rules are applied at the sub-category level. Categories serve three main purposes:
For Email and SMS channels, vendor is configured at root-category level. This is done to solve for the following use cases:
  • Many companies separate promotional and transactional traffic to ensure that opt-outs from promotional messages do not impact critical system notifications.
  • SMS vendors may also expose different APIs for system messages (e.g., OTPs) versus marketing messages.
For Email and SMS, ensure a vendor is configured for the category used in the workflow; otherwise, delivery will fail.
We maintain separate notification queues for different notification categories to ensure that marketing and promotional notifications don’t delay system or time-sensitive notifications.
You can create sub-categories for different types of notifications and give your users and tenants the option to set their notification preferences at the category level.See how to set it up in the next document.

​
Mental model

Notification categories use a functional hierarchy: Root-category → Section → Sub-category
ConceptDescription
Root-categoryChoose one of three: System, Transactional, or Promotional. This determines which notification queue or vendor to pick for the workflow. Preferences are not applied at the root-category level. You can’t create new ones.
Sub-categorySub-categories are created inside a root-category to manage user preferences. When sub-category is assigned to the workflow, user preferences are evaluated before sending the notification. Sub-categories are what users see on preference / unsubscription page and can opt in/out of.
SectionSections are optional UI groupings used to organize sub-categories on the preference page.
Example structure: 
Promotional (root category)
 └── Marketing (section)
  ├── Newsletters (sub-category) ← Use sub-category slug in workflows to apply user preferences
  └── Product Announcements (sub-category)
When users visit their preference page, they see sub-categories organized under sections. Root-categories control delivery behind the scenes but aren’t shown to users.

​
Root-categories

SuprSend has three root-categories — System, Transactional, and Promotional — which define latency and queueing behavior. Sub-categories are always created inside one of these three. How it works:
  • Notification queues and vendors are inherited from the root-category at sub-category level
  • User or tenant preferences are applied at the sub-category level
  • Root-categories are not shown to users—only sub-categories appear on preference pages

​
System

Essential notifications that users can’t unsubscribe from. Common examples: OTP, Forgot Password, Incident reports

​
Transactional

Notifications sent in response to user actions or transactions. Common examples: Payment confirmation or reminders, Booking confirmation, Post shared/liked, Balance alerts, Account updates

​
Promotional

Notifications sent to promote products or re-engage users to your platform. Common examples: Newsletters, Announcements, Product updates, Sales/events, Deals and discounts, Price drop alerts
Promotional notifications are sent in bulk and consume significant pipeline resources. To ensure that marketing notifications doesn’t impact the latency of product alerts, always use the promotional category for bulk messages and broadcasts.

​
Sections and Sub-Categories

​
Sub-categories

Sub-categories are where notification preferences are applied. This is what appears on the preference page and what users can opt in/out of. Assign category slug to the workflow. You’ll get the slug by clicking on the sub-category on Preference page.

​
Sections

Sections are used to organize related sub-categories on the preference page. Think of them as folders that help users find notifications more easily. They are just used for visual grouping and are not used to apply preferences. Example: Quotes is a section containing the Quote Approval and Forecast sub-categories:

​
Default preferences

Default preferences determine how users receive notifications when they haven’t set their own preferences. Configure these at the sub-category level when setting up categories. Preference modes:
  • On: Users receive notifications by default
  • Off: Users must opt in to receive notifications
  • Can’t Unsubscribe: Users cannot fully opt out (required notifications)
When using Can’t Unsubscribe, channel-level opt-in/out still applies unless channels are marked mandatory. For detailed information on configuring default preferences, preference modes, and recommended defaults, see Default Preferences.

​
Setting per-user and tenant preferences

Users and tenants can set their notification preferences at the sub-category level. Users can opt in or out of specific sub-categories, channels or channels within a category, and tenants can set default preferences that apply to all their users. 
Default Preference (Sub-category)
      ↓ (tenant override)
Tenant Preference (Applies to all users of the tenant)
      ↓ (user override)
User Preference (Final preference)
Override Rules:
  • Tenants can override the default sub-category preference for their entire user base at the tenant level.
  • Users can override the tenant-level preference for themselves at the user level.
  • Once a tenant or user overrides a sub-category preference, changes to the default preference in that sub-category no longer affect them.
For details, see User Preferences and Tenant Preferences.

​
Tags

Tags are used to filter categories on the preference page. Common usecases are to filter categories based on user role or department. Tags added at the section level are inherited by all sub-categories inside 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.

​
Category translations

This feature is only available for Enterprise plan customers or the ones who have enabled translation feature in their account.
Translate categories and sections into users’ locale by uploading .json translations for each locale. Translations go live immediately after upload—no commit or publish required. How it works:
  • English (en) is always available as the base language and is auto-generated from the category names and descriptions you define.
  • You can download en.json file, translate it into your desired locale and upload it back.
  • While loading preference page, pass the locale parameter to the API or preference SDK and the translations will be loaded for that locale.
  • If a translation is missing for a specific locale or key in the passed locale, the system automatically falls back to first regional locale, and then to English.
    Example: User’s locale is set to locale=es-AR and translation is missing for one of the categories in es-AR.json, it will look for translation of that category first in es.json, then falls back to en.json if needed.