Build a preference center

Give users one place to choose which messages they receive, and on which channels. Configure topics once in the editor. Then show them as a Courier-hosted page or an embedded component. Both read and write the same preference data.

Prerequisites

A Courier workspace

Configure the topics

Use the (Platform → Preferences). Topics, sections, and branding are all defined here. Every setting it exposes is in .

The preferences editor: page settings, sections, and topics, with a live preview of the hosted page.

Set page settings

Page settings apply to the whole page:

An optional , for logo and colors.
The heading and description.
The channel names users see. Rename them to match your product, for example “In-App” to “Inbox”.

Add sections

Sections group related topics under a heading you name, such as “Account” or “Marketing”. Turn on channel selection for a section to let users pick which channels deliver its topics.

Add topics

Topics are the categories users opt in or out of. For each one, set a name, its section, and a default state:

On (OPTED_IN): users receive it unless they opt out.
Off (OPTED_OUT): users receive nothing until they opt in.
Required (REQUIRED): users cannot opt out. Use it for critical messages, and leave unsubscribe links off templates mapped to required topics.

Map templates to topics

Mapping a template to a topic makes Courier enforce the preference on every send. Set it in a template’s in Design Studio, or set the template’s subscription field to { "topic_id": "<TOPIC_ID>" } through the API.

Publish

Every change saves as a draft. Use Preview Page to open the page in draft mode, then Publish to make it live. Until you publish, users see the last published version.

To batch a topic’s messages on a schedule, open the topic’s digest settings and link a digest template. See the for how batching, categories, and Trigger empty behave.

Hosted page

The hosted preference center needs no frontend. It lists the user’s subscription topics with the heading, description, and optional brand you set in the editor. It works on desktop and mobile. Courier serves it at https://view.notificationcenter.app/p/<id>. The id encodes the workspace, brand, and user, so each recipient sees their own preferences.

A branded Courier-hosted preference page with Account Notifications and Marketing sections, per-topic toggles, a Required topic, and a digest delivery schedule — The Courier-hosted preference page a user opens from the preferences link: their subscription topics, grouped into sections and branded.

Link users to the preference center

Link users to their hosted page with the preferences variable. Courier renders it as a secure, per-user URL. Include to.user_id in your send so each recipient gets their own link. Write the variable in the format for your editing context:

Content blocks (Text, Markdown, Quote, List): {{$.urls.preferences}}
Handlebars (Template blocks, email and brand templates): {{var "urls.preferences"}}
Elemental JSON (action buttons and links): {$.urls.preferences}

Put the variable in a saved template, then send that template with the . Below, nt_01kx4h2jdafq8bk9aftxak4b40 is a template whose body includes {{$.urls.preferences}}:

import Courier from "@trycourier/courier";

const client = new Courier({
  apiKey: process.env["COURIER_API_KEY"],
});

const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

console.log(requestId);

import os

from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)
print(response.request_id)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

puts(response)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .build())
    .build();

var response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40"}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123.

For a one-click opt-out from the topic tied to a message, use the unsubscribe variable the same way ({{$.urls.unsubscribe}}, {{var "urls.unsubscribe"}}, or {$.urls.unsubscribe}).

The URL is empty when the template has no subscription topic, so first. On a required topic the opt-out does nothing, so leave unsubscribe links off those templates.

Place either link inside a message, or once in your footer so it appears on every message.

One-click unsubscribe headers

Gmail and Yahoo require bulk senders to support one-click unsubscribe. Turn on Unsubscribe Headers for a topic in the preferences editor, or set include_unsubscribe_header on the topic through the API. Courier then adds two headers to that topic’s email:

List-Unsubscribe: <the recipient's unsubscribe URL>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Both conditions have to hold for the headers to appear. The topic has the setting on, and the message resolves an unsubscribe URL, which means the template is mapped to that topic.

SendGrid is the only provider Courier emits these headers on today. On another email provider, set them yourself with a .

Embedded component

To keep users inside your product, embed the preference center instead of linking to the hosted page. It reads the same published topics and writes the same preference data, so a change in one place shows up in the other.

The embeddable Courier preferences component, showing a topic section with per-topic toggles and an expanded channel picker for email, push, and SMS — The embedded preference center component: subscription topics with per-topic channel choices.

Setup, theming, and building your own UI live in the In-App Notifications tab:

Add a preference center

Install, authenticate, and render the component on every platform.

Customize Preferences

Theme the component or build your own preferences UI.

Verify

Open the preference center

Open the hosted page from a real send (a message containing {{$.urls.preferences}} with to.user_id set), or load your embedded component as a test user.

Toggle a topic off and send

Toggle a topic off. Send a message mapped to that topic and confirm the log shows the send blocked as UNSUBSCRIBED.

Read the change back

and confirm the status matches what you toggled.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Build a preference center

Prerequisites

Configure the topics

Hosted page

Link users to the preference center

One-click unsubscribe headers

Embedded component

Add a preference center

Customize Preferences

Verify

​Prerequisites

​Configure the topics

​Hosted page

​Link users to the preference center

​One-click unsubscribe headers

​Embedded component

Add a preference center

Customize Preferences

​Verify

Prerequisites

Configure the topics

Hosted page

Link users to the preference center

One-click unsubscribe headers

Embedded component

Verify