Detailed guide on how to set up and capture user notification preferences in SuprSend.
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.
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.
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:
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:
opt-out
of does not block notifications from mandatory channels in this category.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.
You can capture user preference choice using an out-of-the-box hosted subscription page or by embedding a preference center within your product.
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.
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}}
.
Additionally to the preference center within SuprSend, communication channels provide their own opt-out options, which SuprSend manages internally.
Email: Unsubscribe URL header
Gmail empathizes with the need to add 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.
Inbox: Render Preference Page within Inbox
Companies also give option for users to load the Inbox preferences as a separate page within their Inbox or give a link to redirect users to Preference center in their product.
Mobile Push: Preference Page in App settings
For mobile push notifications, users typically manage their preferences through the app settings. The categories set in your workflow also pass as push categories. If you set preference categories, the system automatically reflects them in the user’s app settings, loading similar preference controls.
SMS & Whatsapp: Reply `STOP`
Users generally unsubscribe from Short Message Service (SMS) by replying “STOP.” In SuprSend, the system marks the channel as inactive in the user profile upon receiving this response.
It is always a good practice to show only the categories that are relevant to the user. There are 2 ways to achieve this:
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.
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.
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.
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:
Operator | Operand Datatype | Description | Example |
---|---|---|---|
exists | boolean | Returns categories where any tag is set | tags={"exists":true} |
not | string | Excludes categories that have the specified tag | tags={"not":"admin"} |
or | array | return categories that have any of the mentioned tags | tags={"or":["sales","marketing"]} |
and | array | return categories that have all the mentioned tags | tags={"and":["sales","manager"]} |
You can combine these operators for nested filtering like tags={"or":[{"and":["sales","manager"]},{"and":["marketing","associate"]}]}
.
When a workflow triggers, SuprSend evaluates preferences for each recipient before each delivery node.
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.
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.
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.
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.
How to setup digest schedule in my preferences?
You can create sub-categories for different digest schedules or set the digest schedule in the user profile and pass a dynamic schedule in the workflow digest node. An option to set the digest schedule directly on your preference page will be available soon.
I have a use case where a company has multiple departments/roles, and the admin will set preferences for users in these departments.
You can manage this with tenant preferences. In the SuprSend system, each tenant represents an organization, and the administrator sets which categories to send to their internal team using the tenant preference API.
What happens to existing user preference view if I change default preference setting?
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.
I have multiple enterprise customers with various product offerings. Customers should only receive notifications for the products they have enabled, and the same should be visible on their preference page. How can I manage this in SuprSend?
You can turn off categories for tenants from the tenant page on the SuprSend console. Turning off the preference for a category automatically removes it from the tenant preference APIs and UI view. To further apply this to the tenant’s users, set visible to subscriber
to false
in the default tenant preferences to hide the category from the tenant’s end users.