Set Up a Hosted Preference Center

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

Open the Preferences Editor

Navigate to Settings > Preferences Editor in the Courier dashboard.

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 — Creating a new subscription topic

Set the Default State

Choose whether users start opted in, opted out, or are required to receive this topic:

Default State	Behavior
On	Users receive notifications unless they opt out
Off	Users must opt in to receive notifications
Required	Users cannot opt out (e.g. security alerts, billing)

For most notification categories, On is appropriate. Use Required sparingly for critical communications.

Configure Unsubscribe Headers

Each topic has an Unsubscribe Headers setting that controls whether Courier includes List-Unsubscribe headers in emails sent for this topic:

Setting	When to use
Off	Transactional messages (order confirmations, password resets) that users should always receive
On	Marketing 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.

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 — Preference section grouping related topics

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.

Open Topic Settings

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

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.

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.

Step 3: Add Preference Links to Notifications

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

Open your brand in Settings > Brands
Select Custom MJML/Handle Bars as the Template Type
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>

Custom MJML brand template with preference link in footer

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.

Step 4: Add Unsubscribe Links (Recommended)

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:

Context	Syntax
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.

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.

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_API_KEY"

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "your_api_key" });

const { items } = await client.users.preferences.retrieve("user_123");

for (const topic of items) {
  console.log(`${topic.topic_name}: ${topic.status}`);
}

from courier import Courier

client = Courier(api_key="your_api_key")

response = client.users.preferences.retrieve("user_123")

for topic in response.items:
    print(f"{topic.topic_name}: {topic.status}")

Update a User’s Topic Preference

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

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "your_api_key" });

await client.users.preferences.updateOrCreateTopic("TOPIC_ID", {
  user_id: "user_123",
  topic: {
    status: "OPTED_IN",
  },
});

from courier import Courier

client = Courier(api_key="your_api_key")

client.users.preferences.update_or_create_topic(
    "TOPIC_ID",
    user_id="user_123",
    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_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": {
      "status": "OPTED_IN",
      "has_custom_routing": true,
      "custom_routing": ["email"]
    }
  }'

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "your_api_key" });

await client.users.preferences.updateOrCreateTopic("TOPIC_ID", {
  user_id: "user_123",
  topic: {
    status: "OPTED_IN",
    has_custom_routing: true,
    custom_routing: ["email"],
  },
});

from courier import Courier

client = Courier(api_key="your_api_key")

client.users.preferences.update_or_create_topic(
    "TOPIC_ID",
    user_id="user_123",
    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

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

Set Up a Hosted Preference Center

Prerequisites

Step 1: Create Subscription Topics

Step 2: Map Templates to Topics

Step 3: Add Preference Links to Notifications

In Content Blocks

In Handlebars Templates

In Elemental JSON

In Brand Footer

Step 4: Add Unsubscribe Links (Recommended)

Step 5: Preview and Test

Step 6: Manage Preferences Programmatically (Optional)

Fetch a User’s Preferences

Update a User’s Topic Preference

Set Custom Routing (Enterprise)

What’s Next

Embed Preferences in React

Preferences Editor Reference

Hosted Page Reference

User Preferences API

​Prerequisites

​Step 1: Create Subscription Topics

​Step 2: Map Templates to Topics

​Step 3: Add Preference Links to Notifications

​In Content Blocks

​In Handlebars Templates

​In Elemental JSON

​In Brand Footer

​Step 4: Add Unsubscribe Links (Recommended)

​Step 5: Preview and Test

​Step 6: Manage Preferences Programmatically (Optional)

​Fetch a User’s Preferences

​Update a User’s Topic Preference

​Set Custom Routing (Enterprise)

​What’s Next

Embed Preferences in React

Preferences Editor Reference

Hosted Page Reference

User Preferences API

Prerequisites

Step 1: Create Subscription Topics

Step 2: Map Templates to Topics

Step 3: Add Preference Links to Notifications

In Content Blocks

In Handlebars Templates

In Elemental JSON

In Brand Footer

Step 4: Add Unsubscribe Links (Recommended)

Step 5: Preview and Test

Step 6: Manage Preferences Programmatically (Optional)

Fetch a User’s Preferences

Update a User’s Topic Preference

Set Custom Routing (Enterprise)

What’s Next