Skip to main content


Fine-grained preferences management for your users.

Courier Preferences enables your users to set fine-grained preferences over the notifications they receive.

Courier Preferences allow a user to determine which notifications and channels they receive. These notifications are grouped into a preference array that you can then use to integrate a pre-built notification center into your notifications.

Prerequisite: User Id

In order for a recipient to successfully set their preferences from a notification, you must include to.user_id in the Send request. This is because the user_id ties the recipient profile to their set preferences. If no user_id is present in the request, the preferences method will not register.

How Preferences Work

Preferences take your existing notification templates and allow you to group them into an array of preferences your users can easily customize. This array of preferences is made up of subscription topics and preference Sections. Notification templates that contain similar information can be grouped into subscription topics. Subscription topics that contain a similar grouping of notifications and channels can be integrated into preference sections.

You can create and manage these sections and topics in the Preferences Designer. Once created, you can use our new hosted Preference Center, preferences react component, or preferences APIs. We recommend you use our new hosted Preference Center, as it’s as simple as adding a link to your notification templates or brands in a few steps.

What is a Subscription Topic?

Subscription topics are groups of notifications your users can opt-in and out of.

  • If you’re a ride-sharing company, one of your topics might be promotions. In Courier you can create a subscription topic for each type of notification your user wants to manage.
  • If you’re a bank, you might have required and optional account updates. In this case, having both topics would ensure users have control over the optional account updates.

Note: Topics can have many notification templates attached to them, but not vice versa.

All subscription topics come with a default state of “on”, “off”, or “required”. By default, every subscription topic is set to “on” so that users will receive notifications attached to this topic. Subscription topics with their default state set to “off” allow their users to opt-in to notifications instead of receiving them by default. A default state set to “required” will prevent users from opting out of those notifications.

Learn more about Subscription Topics here.

What is a Preference Section?

Preference sections are groups of subscription topics that your users can manage their preferred communications channels with.

  • If you’re an internet financial infrastructure company, one of your sections might be “Payments”. In Courier, you can create a preference section and enable users to select interchangeably between Slack, Email, and Text as their preferred method of communication.

Note: Preference sections can have many subscription topics attached to them, but not vice versa.

Courier Preferences supports all four of our Courier Channels including webhooks out of the box. Enabling your users to customize their preferred method of communication is called “Channel Delivery Customization” and is currently available for our enterprise-tier customers. Request a demo.

Learn more about Preference Sections here.

Using your Preferences

The quickest way to get started with Courier Preferences is to use our Preferences Designer to create a hosted Preference Center for your users. Like our unsubscribe link, the Preference Center can be integrated into a notification template or a brand. Here is our getting started guide.

Please note that when sending a notification, Courier Preferences relies on the user_id to track which preferences a user has set and to respect those preferences. This id is customizable and can be set when you send a notification to our send endpoint.

Also, when sending a notification that is linked to a subscription topic, please note that user preferences set to that topic are respected first before other preferences, notification conditions, or channel conditions. If you’ve set a topic ad-hoc in the send call, the user preferences set to that topic will be respected first.

Learn more about the Preferences Designer here.

Hosted Preference Center

The hosted Preference Center is a customizable page that displays the topics and sections so users can set their preferences. This page can be created and managed in the Preferences Designer. For enterprise customers, the page is styled by your default brand and displays your logo and links in the header and footer respectively. Courier does not currently support customized domains on this page, support for this is coming soon.

Learn more about the hosted Preference Center here.

Was this helpful?