User Preferences

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

channel_preferences — Global channel opt-outs (e.g., opt out of all email)
categories — Category-level preferences (opt in/out of all channels of a notification type)
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:

User Preference — Individual user’s explicit choices (highest priority)
Tenant Default Preference — Default preferences set by tenant for the category
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

On — Users receive this category's notifications by default

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)

Off — Users must opt in to get notifications

Users will not receive notifications unless they change the preference.

Can't Unsubscribe — Users cannot opt out of mandatory channels in this category

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

Embeddable preference page

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.

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.

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	Returns categories that match any of the provided tags	`tags={ "or": ["sales", "marketing"] }`
`and`	array	Returns categories that match all provided tags	`tags={ "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

You’ll first need to upload translation files for the locale you want to translate to. See How to manage Category translations for details. Once translation files are updated, pass a locale parameter (e.g., es, fr, de) when loading the embeddable preference center or pass locale as query parameter in the get user preference API.

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.

Email: Unsubscribe URL header

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.

Inbox (In-App): Render preference page inside your Inbox

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.

Mobile Push: Preference Page in App settings

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.

SMS & Whatsapp: Reply `STOP`

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

How do I set up a digest schedule?

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.

Why don't I see the 'inbox' channel in my user preferences?

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.

Why do users still receive promotional notifications even after unsubscribing from all categories?

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 instead of the top-level category. This allows users to:

See and control preferences for each notification type
Opt out of specific sub-categories
Have their preferences respected when you send notifications

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.

Can I use user preferences in workflow branching to control which notifications are sent?

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), you can:

Store the same preference data as custom properties in the user profile
Use those custom properties in branch conditions to route notifications

Example use case: If you want to combine multiple notification scenarios (e.g., “New Comment”, “Reply on my comment”, “I am mentioned”) in a single workflow to avoid duplicate notifications, you can:

Store user preferences for each scenario as custom properties (e.g., wants_new_comment_notifications: true, wants_mention_notifications: true)
Use branch conditions to check these properties and route notifications accordingly
This allows you to have one workflow that handles all scenarios while respecting user preferences

Alternative approach: Create separate workflows for each notification scenario with conditions in the Trigger node. Each workflow can use its own preference category, allowing users to control each scenario independently.

How do I let users control both notification on/off and the time they want to be reminded (e.g., medicine reminders)?

You can combine preference categories with dynamic digest schedules to achieve this:1. Set up preference categories:

Create a preference category (e.g., “medicine-reminders”) that users can opt in/out of using the preference APIs or preference center UI.

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({
  "medicineReminderTime": {
    "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".medicineReminderTime).
The digest will only send if the user has opted in to the category, and it will send at their preferred time.

Implementation flow:

Client side (React Native): Capture user’s time preference and call your backend API
Server side (Supabase Edge Function): Update both the user’s preference (opt in/out) via SuprSend preference API and store the time preference as a user property
Workflow: Use preference category to control on/off, and dynamic schedule to control timing

For detailed information, see Dynamic Schedule in the digest documentation.

Notification Categories - Setting up categories & defaults
Manage Categories and Preferences - Complete guide to setting up and managing categories and preferences
Tenant Preferences - Managing tenant-level preferences
Preference Evaluation - How SuprSend evaluates preferences at runtime

GETTING STARTED

CORE CONCEPTS

WORKFLOW BUILDER

Notification Inbox

PREFERENCE CENTRE

VENDOR INTEGRATION GUIDE

INTEGRATIONS

MONITORING & DEBUGGING

MANAGE YOUR ACCOUNT

How It Works

Three Levels of Control

What are user preferences?

How preferences are determined

Setting up preference categories