Skip to main content
Before you start: Make sure you’ve set up notification categories first. See Manage Categories and Preferences for step-by-step instructions.
Preferences let users control which notifications they receive. Instead of an all-or-nothing approach, users can opt out of specific categories, choose preferred channels, and set notification frequency. This granular control reduces the chance that users disable all notifications from your platform. SuprSend provides ready-made UI components and APIs to build preference screens where users can opt in or opt out of different notification categories and channels. This works for both B2B and B2C applications.

How It Works

Preferences are evaluated in priority order: User Preference → Tenant Default → Category Default

Three Levels of Control

Global channel opt-outs, category preferences, and channel opt-outs within categories

​
What are user preferences?

Preferences only work with sub-categories: User preferences apply to sub-categories you create, not root-categories (System, Transactional, Promotional). Use sub-category slugs in workflows for preferences to work.
Each user has a preference set that controls which notifications they receive. A preference set has three levels of control:
  1. channel_preferences — Global channel opt-outs (e.g., opt out of all email)
  2. categories — Category-level preferences (opt in/out of all channels of a notification type)
  3. opt_out_channels — Opt-in/out of specific channels within a category
Example: 
{
  "channel_preferences": [
    { 
        "channel": "email", 
        "is_restricted": true 
    }
  ],
  "categories": [
    { 
      "category": "invoice-ready", 
      "preference": "opt_out" 
    },
    {
      "category": "payment-reminder",
      "preference": "opt_in",
      "opt_out_channels": ["slack"]
    }
  ]
}
In this example: user opted out of email globally, opted out of invoice-ready category completely, and stays opted in to payment-reminder but without Slack.

​
How preferences are determined

When a user hasn’t set their own preferences in a category, SuprSend uses defaults in this order:
  1. User Preference — Individual user’s explicit choices (highest priority)
  2. Tenant Default Preference — Default preferences set by tenant for the category
  3. Category Default Preference — Default preferences set at the category level (lowest priority)
Preference precedence: User Preference → Tenant Default Preference → Category Default Preference
Preference precedence is determined at category level. So, if a user overrides preference for a category but doesn’t touch other categories, defaults continue to apply to the untouched categories.

​
Setting up preference categories

Before users can set their preferences, you must first create and configure preference categories. For step-by-step setup instructions, see Manage Categories and Preferences.

​
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.

​
What default preferences control

Default preferences control:
  • Channel or Category defaults: Which categories or channels will be turned on/off by default on users’ preference page.
  • Mandatory channels: Which channel or category users cannot opt out of (shown as disabled on preference page)
  • Visibility: Whether a category appears on the preference page

​
Preference types

Users will receive notifications in this category by default. You can configure Opt-in Channels to specify which channels are included in the default “On” state:
  • All: All available channels are enabled by default
  • Selected Channels only: Only specific channels you select are enabled by default (e.g., Email, Android Push, iOS Push, In-App Inbox, MS Teams, Slack)
Users will not receive notifications unless they change the preference.
Prevents users from fully opting out of the category. When selected, you can configure:
  • Mandatory Channels: Channels which can’t be opted out of by the user. Set to “All” or “Selected Channels”.
  • Opt-in Channels: In case of “Selected” Mandatory Channels, you can configure the channels that will be opted in by default. Channels other than mandatory and opt-in will be skipped for sending notification unless user explicitly opts in to them.
Even when a category is set to “Can’t Unsubscribe,” users can still control channel-level preferences if your channel-level settings allow it.
This configuration gives you fine-grained control over which channels a user is opted into by default, letting you differentiate between must-deliver channels, default-on channels, and optional channels.

​
Capturing user preferences

Users can set their preferences through one of the following methods:

​
Hosted preference page

Once you publish preference categories, SuprSend automatically generates a dedicated unsubscription webpage for collecting user preferences. Users can set channel-specific preferences from the hosted page. If the link is included in an email, the hosted page will show and save email preferences.

Include it in your templates using {{$hosted_preference_url}}.
This page is currently hosted on a SuprSend domain, but you can reach out to [email protected] if you’d prefer it hosted on your own domain.

​
Embed in your product

You can embed the preference interface directly inside your product using SuprSend’s ready-made UI components. SDKs exist in the languages below. Update your product preference page link on the tenant page and render it in templates using {{$embedded_preference_url}}.

Javascript

React

Angular

​
Controlling what categories to show on UI

It’s always a good practice to show only the categories that are relevant to the user. There are two ways to achieve this:

​
Hide categories for tenant users

In a multi-tenant setup, tenants or admins can control which categories their users see. Setting visible_to_subscriber: false in tenant preferences hides the category from tenant users’ preference pages. Hidden categories won’t send notifications to those users, even if they previously opted in.

​
Filter categories with tags

Use tags to show categories based on user roles, departments, or teams. Filter categories in the preference center using the tags query parameter.
1

Setting Preference tags

Tags can be added to sections and sub-categories directly from Developers → Notification Categories in the SuprSend Console. When a tag is assigned at the section level, it automatically applies to all categories under that section—so filtering by a section tag also filters its child categories.Tags Within Preference Categories
2

Filter Categories with Tags

You can filter categories using the tags query parameter in the API. This can be a simple tag match (e.g. tags=tag1) or a more advanced filter using logical operators.Supported operators:
OperatorOperand DatatypeDescriptionExample
existsbooleanReturns categories where any tag is settags={ "exists": true }
notstringExcludes categories that have the specified tagtags={ "not": "admin" }
orarrayReturns categories that match any of the provided tagstags={ "or": ["sales", "marketing"] }
andarrayReturns categories that match all provided tagstags={ "and": ["sales", "manager"] }
You can combine these operators for nested filtering like tags={ "or": [{ "and": ["sales", "manager"] }, { "and": ["marketing", "associate"] }] }.If no tags are provided, the preference center returns all visible categories.
For details on how tags work, see Tags.

​
Translating preference categories in user’s locale

  • Upload translation files for your category names and descriptions. See How to manage Category translations for details.
  • Once uploaded, pass a locale parameter (e.g., es, fr, de) when:
  • On hosted preference page,
    • Dynamic content (category names, descriptions) is translated using translation files you upload.
    • Static content (CTA text, labels, buttons, etc.) is translated automatically using SuprSend’s built-in i18n support for commonly used languages. You can see the list of supported languages below.
LanguageCode
Englishen
Spanishes
Frenchfr
Germande
Italianit
Portuguesept
Catalanca
Russianru
Dutchnl
Polishpl
Japaneseja
Vietnamesevi
LanguageCode
Indonesianid
Koreanko
Serbiansr
Norwegianno
Hebrewhe
Chinesezh
Finnishfi
Swedishsv
Czechcs
Lithuanianlt
Arabicar

​
How preferences are evaluated

SuprSend evaluates user preferences at send time. For every recipient, the system checks user-level preferences first, then tenant-level overrides, and finally category defaults. For detailed information on the evaluation process, see Preference Evaluation.

​
Other ways to unsubcribe from notifications

In addition to the preference center within SuprSend, communication channels provide their own opt-out options, which SuprSend manages internally.
Gmail requires an unsubscribe URL in email headers when sending bulk emails (5,000+ emails/day). Most email providers expect you to add your own unsubscription page or offer a basic all-or-nothing opt-out option. You can add {{$hosted_preference_url}} here to load the SuprSend hosted preference page from the email header.
Companies also give users the option to load preference settings inside their in-app Inbox or provide a link to redirect users to the Preference center in their product.
For mobile push notifications, users typically manage their preferences through the app settings. The category you assign in your workflow is also sent as the push “category” (used by Android/iOS to group notifications). If you set preference categories, the system automatically reflects them in the user’s app settings, loading similar preference controls.
Users generally unsubscribe from Short Message Service (SMS) by replying “STOP.” SuprSend automatically marks the SMS channel as inactive in the user’s profile when it receives a STOP reply. For WhatsApp, opt-out behavior depends on the provider; where supported, users can reply STOP and SuprSend will mark the channel inactive.

​
FAQ

Users can opt in or opt out of digest notification categories using preference categories. To let users control the timing of digest notifications (e.g., daily at 9 AM), store their preferred schedule as a custom property in their user profile and reference it in your workflow’s digest node. Checkout the digest dynamic schedule documentation for more details.
user.set({
  "digestSchedule": {
    "frequency": "daily",
    "time": "09:00"
  }
})
Changing the default preference for a category doesn’t affect users who have already made changes to that category. For categories where users haven’t made any changes, the preferences update according to the new default settings.
You can turn off categories for tenants from the SuprSend dashboard -> tenant details page -> global preference settings. Turning off the preference for a category automatically removes it from the tenant preference APIs, UI view and also from user’s preference page.
The inbox channel preference is behind a feature flag and needs to be enabled for your account. If you don’t see the inbox channel in your user preferences, contact [email protected] to have the feature flag enabled for your workspace.
Unsubscribing from top-level categories (System, Transactional, Promotional) is not supported. Preferences only work with sub-categories you create.If you’re sending notifications using a top-level category like "promotional" in your workflows, users cannot unsubscribe from those notifications through the preference center, even if they unsubscribe from all visible categories.Solution: Create sub-categories under the Promotional category (e.g., “Marketing”, “Newsletter”, “Product Updates”) and use those sub-category slugs in your workflows.Best practice: Organize notifications into meaningful sub-categories rather than using top-level categories directly. This provides users with granular control and improves their experience.
User preferences are not passed in the workflow payload, so you cannot directly access them in branch conditions or other workflow nodes.Workaround: If you need to use preference-based logic in workflows (e.g., to route notifications based on user preferences or combine multiple notification scenarios in a single workflow), we suggest creating different workflows for each notification scenario and adding invoke workflow node to trigger a different workflow from within another workflow.
You can combine preference categories with dynamic digest schedules to achieve this:1. Set up preference categories:2. Store time preference as user property:
  • When users select their preferred reminder time, store it as a custom property in their user profile. For example:
user.set({
  "meetingReminderTime": {
    "frequency": "daily",
    "time": "09:00",
    "tz_selection": "recipient"
  }
})
3. Use dynamic schedule in digest node:
  • In your workflow’s digest node, configure it to use a dynamic schedule that references the user property (e.g., ."$recipient".meetingReminderTime).
  • The digest will only send if the user has opted in to the category, and it will send at their preferred time.
For detailed information, see Dynamic Schedule in the digest documentation.