Preferences allow users to opt out of notification categories, choose their preferred communication channels, and set the frequency of notifications. Providing granular preferences reduces the likelihood of users disabling all notifications from your platform.

In SuprSend, you can use ready-made UI and APIs to manage multi-tenant preference use cases. This includes letting admins set preferences for internal teams and handle notifications for enterprise customers, where companies, customers, and end users have distinct preferences.

​
How preferences work?

Each user has a preference set within SuprSend, and users receive notifications in the category and channel they haven’t opted out of. If a user hasn’t configured preferences for a category, the system uses default preferences.

Preference set contains three level of preferences: channel_preferences (for channel-level opt-outs), categories, and opt_out_channels within each category. In the below example, user has opted out of email, invoice-ready category and slack channel in payment-reminder category.

{
  "channel_preferences": [
    {
      "channel": "email",
      "is_restricted": true
    }
  ],
  "categories": [
    {
      "category": "invoice-ready",
      "preference": "opt_out"
    },
    {
      "category": "payment-reminder",
      "preference": "opt_in",
      "opt_out_channels": [
        "slack"
      ]
    }
  ]
}

​
Set up preference categories in SuprSend

​
Create notification category

To set up notification preferences, start by creating notification categories. Instead of creating a separate category for each trigger, group similar notifications to keep categories more user-friendly. You can also add sections to organize your categories more effectively.

Don’t add too many categories as it can drive users to use channel level opt-outs.

Creating Billing section

Adding categories in Billing section

You can update notification categories from the Developers → Preference categories page. Add categories under any of the three predefined root categories:

  • System: For critical system notifications like OTPs, verification, and authentication. Users can’t opt out of this category.
  • Transactional: Notifications related to user transactions on your platform, such as payment confirmations, delivery statuses, and comments. The default preference for this category opts users in, but you can change it at the individual category level.
  • Promotional: Marketing notifications like newsletters, announcements, deals, and discounts. The default preference for this category opts users out, but you can change it at the individual category level.

​
Set default preferences

If the user hasn’t set preferences in a category, the system sends notifications based on default preferences. Default preferences are set in the notification category. The tenant can override the default preferences for their users, either through the tenant preference API or from the tenant details page.

You can set following default preferences at category level:

  1. On : opt-in on all channels
  2. Off : opt-out on all channels
  3. Can’t Unsubscribe : Use this to prevent users from completely opting out of critical notification categories, such as anomaly alerts or important transactions (e.g., completed trades, payments). Channel opt-out of does not block notifications from mandatory channels in this category.

​
Map category to notifications

Once set, publish your preference categories to see the latest categories in workflow. You can then map these categories when configuring your workflow for preferences to take effect.

​
Capture user preferences

You can capture user preference choice using an out-of-the-box hosted subscription page or by embedding a preference center within your product.

​
Hosted Preference Page

Once you publish preference categories, SuprSend automatically generates a dedicated webpage for collecting out-of-the-box user preferences. Users can set channel-specific preferences from the hosted page. e.g., if you add it to your email, the page displays only the relevant preference categories for email, and the user’s selections save for email. Include it in your templates using {{$hosted_preference_url}}.

This page currently hosts on the SuprSend domain, but you can reach out if you’d prefer it hosted on your own domain.

​
Embed in your product

You can load the preference interface inside your product using the ready UI code. 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

​
Channel specific unsubscription options

Additionally to the preference center within SuprSend, communication channels provide their own opt-out options, which SuprSend manages internally.

​
Controlling what categories to show on UI

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

  1. Turning off category visibility for all users of a tenant: In a multi-tenant setup, if tenants or admins decide what categories their users should see, you can control this via the visible_to_subscriber: false flag in default tenant preferences.

  2. Setting custom preference UI for each user: Use tags to show categories based on user roles, departments, or teams. These tags can then be used to filter categories in preference center.

1

Setting Preference tags

Tags can be added to categories and sections directly from the SuprSend Console → Preference Page. 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.

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"}
orarrayreturn categories that have any of the mentioned tagstags={"or":["sales","marketing"]}
andarrayreturn categories that have all the mentioned tagstags={"and":["sales","manager"]}

You can combine these operators for nested filtering like tags={"or":[{"and":["sales","manager"]},{"and":["marketing","associate"]}]}.

​
Preference evaluation at runtime

When a workflow triggers, SuprSend evaluates preferences for each recipient before each delivery node.

1

Evaluating Recipient preferences

If recipient preferences aren’t set, the system picks the default preference setting. Once the user sets a preference in a category, changes to the default preference of existing categories won’t affect recipient preferences.

2

Factoring in tenant preferences

If you are triggering notification for a tenant, tenant default preference setting takes precedence over default preference set at category level.

3

Resolving preference conflicts

The order of precedence is always user > tenant > org (set in notification category settings). However, if you turn off notifications in a category from the tenant page, users will not receive notifications in that category.

4

Debugging preference evaluation in workflow runs

User preferences can change over time, and when checking a workflow run, you need to know what user preferences were at that time. You can view this using the step-by-step debugger in workflow executions.

You can also track when user updated their preference by filtering on Subscriber preference update in request logs.

​
Frequently asked questions