Skip to main content
Give your users a branded page where they control which notifications they receive and how. This tutorial walks through the full setup: creating topics in the Preferences Editor, connecting them to templates, and adding preference links to your notifications. By the end, your users will be able to visit a hosted page to opt in/out of notification categories and (on Enterprise plans) choose delivery channels.

​
Prerequisites

  • A Courier account with at least one configured provider (e.g. SendGrid, Twilio)
  • At least one published notification template

​
Step 1: Create Subscription Topics

Subscription topics are the notification categories your users can control. For example: “Product Updates”, “Marketing”, “Security Alerts”.
1

Open the Preferences Editor

Navigate to Settings > Preferences Editor in the Courier dashboard.
Preferences Editor
2

Create a Subscription Topic

Click Add Topic and give it a user-facing name (e.g. “Product Updates”). This name is what your users will see on the preference page.
Topic editor modal
3

Set the Default State

Choose whether users start opted in, opted out, or are required to receive this topic:
Default StateBehavior
OnUsers receive notifications unless they opt out
OffUsers must opt in to receive notifications
RequiredUsers cannot opt out (e.g. security alerts, billing)
For most notification categories, On is appropriate. Use Required sparingly for critical communications.
4

Configure Unsubscribe Headers

Each topic has an Unsubscribe Headers setting that controls whether Courier includes List-Unsubscribe headers in emails sent for this topic:
SettingWhen to use
OffTransactional messages (order confirmations, password resets) that users should always receive
OnMarketing messages (newsletters, promotions) where email clients should show an unsubscribe option
When enabled, email clients like Gmail and Apple Mail display a native “Unsubscribe” button in the message header, which helps with deliverability and compliance.
5

Create a Preference Section (Optional)

Click Add Section to group related topics together on the preference page. For example, a “Marketing” section might contain “Product Updates”, “Newsletter”, and “Event Invitations”.If you don’t create sections, all topics appear in a flat list.
Topic section example
For full details on topic and section configuration, see the Preferences Editor reference.

​
Step 2: Map Templates to Topics

Connect your notification templates to subscription topics so Courier automatically respects user preferences when sending.
1

Open Topic Settings

In the Preferences Editor, click the topic you created and look for the Linked Notifications section.
Linked Notifications in topic settings
2

Link Your Templates

Select the notification templates that belong to this topic. When a user opts out of the topic, Courier suppresses all linked templates for that user.
Each template can only be mapped to one subscription topic at a time.
3

Publish Your Changes

Click the Publish button in the Preferences Editor. Changes to topics, sections, and template mappings are saved as a draft until you publish. Your hosted preference page and embedded components will not reflect updates until you publish.
You can also set the topic when creating or editing a template in the Template Designer. Insert preference center URLs into your notification templates so users can access their settings. Courier generates unique, authenticated URLs per user; no additional auth setup is needed.

​
In Content Blocks

If your template uses the visual editor with content blocks (text, markdown, quote, list), use: 
{$.urls.preferences}

​
In Handlebars Templates

If your template uses Handlebars syntax (template blocks, email templates, brand templates): 
{{var "urls.preferences"}}

​
In Elemental JSON

If you build notification content programmatically with Elemental: 
{
  "type": "action",
  "content": "Manage Preferences",
  "href": "{$.urls.preferences}",
  "style": "button"
}
To show the preference link on every notification automatically, add it to your brand footer. This requires a Custom MJML/Handlebars brand template (the standard template only supports social links in the footer).
  1. Open your brand in Settings > Brands
  2. Select Custom MJML/Handle Bars as the Template Type
  3. In the MJML Footer section, add a preference link using the Handlebars variable:
<mj-wrapper css-class="footer" background-color="#ffecb8">
  <mj-section background-color="#ffecb8" padding="10px">
    <mj-column>
      <mj-text align="center" color="white">
        <a href="{{var "urls.preferences"}}">Manage Notification Preferences</a>
      </mj-text>
    </mj-column>
  </mj-section>
</mj-wrapper>
Brand footer with preference link in MJML
For details on custom brand templates, see the Brand Designer reference.
Important: Include to.user_id in your send requests for preference links to work. The user ID maps recipients to their preference profiles.
Add one-click unsubscribe links so users can quickly opt out of a specific topic. This is important for email compliance. The variable syntax matches the preference link pattern:
ContextSyntax
Content blocks{$.urls.unsubscribe}
Handlebars{{var "urls.unsubscribe"}}
Elemental JSON"href": "{$.urls.unsubscribe}"
When a user clicks an unsubscribe link, Courier shows a confirmation page and opts them out of the topic associated with that notification.

​
Step 5: Preview and Test

Before going live, verify everything works end-to-end.
1

Preview the Preference Page

In the Preferences Editor, click Preview to see how your preference page looks to users. It automatically applies your brand styling.
Hosted preference center preview
2

Send a Test Notification

Send a test notification to yourself and confirm:
  • The preference link in the notification opens the hosted preference page
  • The unsubscribe link opts you out of the correct topic
  • Opting out actually suppresses future notifications for that topic

​
Step 6: Manage Preferences Programmatically (Optional)

You can also read and update user preferences from your backend using the API or SDKs. This is useful for syncing preferences with your own settings UI or importing existing preferences.

​
Fetch a User’s Preferences

curl -X GET https://api.courier.com/users/{user_id}/preferences \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

​
Update a User’s Topic Preference

curl -X PUT https://api.courier.com/users/{user_id}/preferences/{topic_id} \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": {
      "status": "OPTED_IN"
    }
  }'

​
Set Custom Routing (Enterprise)

Let users control which channels they receive notifications on for a given topic: 
curl -X PUT https://api.courier.com/users/{user_id}/preferences/{topic_id} \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": {
      "status": "OPTED_IN",
      "has_custom_routing": true,
      "custom_routing": ["email"]
    }
  }'
Custom routing requires an Enterprise plan. The notification template must have multiple delivery channels configured and be linked to a subscription topic for channel preferences to take effect.
For full API documentation, see the User Preferences API reference.

​
What’s Next

Embed Preferences in React

Build an in-app preference center with React components

Preferences Editor Reference

Full reference for topic and section configuration

Hosted Page Reference

Detailed hosted preference center documentation

User Preferences API

API reference for managing preferences programmatically