Manage user preferences with the API

The and cover the concepts behind this API.

The User Preferences API reads and writes one user’s topic opt-ins and per-topic channel choices, one topic at a time or the whole set at once. Call it from your backend with your workspace API key (the examples below), or from your frontend with a client SDK as the signed-in user. Every call needs a user_id, the same ID you send to, and single-topic calls also need a topic_id.

Prerequisites

Read a user’s preferences

Reading a user’s preferences returns every topic they have an override for, with their status, the topic’s default_status, and any custom_routing. Fetch them from the :

import Courier from '@trycourier/courier';

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

const preference = await client.users.preferences.retrieve('user_123');

console.log(preference.items);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
preference = client.users.preferences.retrieve(
    user_id="user_123",
)
print(preference.items)

curl -X GET https://api.courier.com/users/user_123/preferences \
  -H "Authorization: Bearer $COURIER_API_KEY"

require "courier"

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

preference = courier.users.preferences.retrieve("user_123")

puts(preference)

preference, err := client.Users.Preferences.Get(
	context.TODO(),
	"user_123",
	courier.UserPreferenceGetParams{},
)

PreferenceRetrieveResponse preference = client.users().preferences().retrieve("user_123");

$preference = $client->users->preferences->retrieve('user_123');

PreferenceRetrieveParams parameters = new() { UserID = "user_123" };

var preference = await client.Users.Preferences.Retrieve(parameters);

courier users:preferences retrieve \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123

With Courier MCP, show me user_123's notification preferences.

Update one topic

Updating one topic creates or changes a single preference. Wrap it in a topic object with a status of OPTED_IN or OPTED_OUT. REQUIRED is a topic default set in the editor, not a user choice, and the API rejects opting a user out of a required topic. To set the channels the user wants, add has_custom_routing: true and list them in custom_routing (email, sms, push, inbox, direct_message, webhook). To opt out entirely, send { "topic": { "status": "OPTED_OUT" } } with no routing. To put the user on one of the topic’s digest schedules, add digest_schedule_id, as in . Call the :

Where custom routing over the API isn’t available, the single-topic write returns 402, the bulk PUT returns 400, and the bulk POST returns 200 with a per-item error. Only status is written.

import Courier from '@trycourier/courier';

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

const response = await client.users.preferences.updateOrCreateTopic('pt_01kx4h2jdafq8bk996nn92357r', {
  user_id: 'user_123',
  topic: {
    status: 'OPTED_IN',
    has_custom_routing: true,
    custom_routing: ['inbox', 'email'],
  },
});

console.log(response.message);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.users.preferences.update_or_create_topic(
    topic_id="pt_01kx4h2jdafq8bk996nn92357r",
    user_id="user_123",
    topic={
        "status": "OPTED_IN",
        "has_custom_routing": True,
        "custom_routing": ["inbox", "email"],
    },
)
print(response.message)

curl -X PUT https://api.courier.com/users/user_123/preferences/pt_01kx4h2jdafq8bk996nn92357r \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic": { "status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["inbox", "email"] } }'

require "courier"

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

response = courier.users.preferences.update_or_create_topic(
  "pt_01kx4h2jdafq8bk996nn92357r",
  user_id: "user_123",
  topic: {status: :OPTED_IN}
)

puts(response)

response, err := client.Users.Preferences.UpdateOrNewTopic(
	context.TODO(),
	"pt_01kx4h2jdafq8bk996nn92357r",
	courier.UserPreferenceUpdateOrNewTopicParams{
		UserID: "user_123",
		Topic: courier.UserPreferenceUpdateOrNewTopicParamsTopic{
			Status:           shared.PreferenceStatusOptedIn,
			HasCustomRouting: courier.Bool(true),
			CustomRouting:    []shared.ChannelClassification{shared.ChannelClassificationInbox, shared.ChannelClassificationEmail},
		},
	},
)

PreferenceUpdateOrCreateTopicParams params = PreferenceUpdateOrCreateTopicParams.builder()
    .userId("user_123")
    .topicId("pt_01kx4h2jdafq8bk996nn92357r")
    .topic(PreferenceUpdateOrCreateTopicParams.Topic.builder()
        .status(PreferenceStatus.OPTED_IN)
        .build())
    .build();
PreferenceUpdateOrCreateTopicResponse response = client.users().preferences().updateOrCreateTopic(params);

$response = $client->users->preferences->updateOrCreateTopic(
  'pt_01kx4h2jdafq8bk996nn92357r',
  userID: 'user_123',
  topic: [
    'status' => PreferenceStatus::OPTED_IN,
    'customRouting' => [
      ChannelClassification::INBOX, ChannelClassification::EMAIL
    ],
    'hasCustomRouting' => true,
  ],
);

PreferenceUpdateOrCreateTopicParams parameters = new()
{
    UserID = "user_123",
    TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
    Topic = new()
    {
        Status = PreferenceStatus.OptedIn,
        CustomRouting =
        [
            ChannelClassification.Inbox, ChannelClassification.Email
        ],
        HasCustomRouting = true,
    },
};

var response = await client.Users.Preferences.UpdateOrCreateTopic(parameters);

courier users:preferences update-or-create-topic \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --topic-id pt_01kx4h2jdafq8bk996nn92357r \
  --topic '{status: OPTED_IN}'

With Courier MCP, opt user_123 into that topic and route it to inbox and email.

To reset a topic to its default, .

Client SDKs

From your frontend, a client SDK updates the signed-in user’s own preferences. It authenticates with a short-lived JWT rather than your API key, issued for that user with the read:preferences and write:preferences scopes. See for the token flow. It can only read and write that one user’s data. The calls this same client. Every client SDK exposes the same preferences methods: getUserPreferences() to list, getUserPreferenceTopic() to read one, and putUserPreferenceTopic() to opt a topic in or out and set its channels. On the web, React, Web Components, Vue, and Angular all call the shared @trycourier/courier-js client (React also through the useCourier() hook). The mobile SDKs expose an identical client.

import { useCourier } from "@trycourier/courier-react";

// After courier.shared.signIn({ userId, jwt }) for the signed-in user:
const courier = useCourier();

await courier.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});

import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});

// Vue uses the same @trycourier/courier-js client behind its component wrapper.
import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});

// Angular uses the same @trycourier/courier-js client behind its component wrapper.
import { Courier } from "@trycourier/courier-js";

Courier.shared.signIn({ userId: "user_123", jwt });

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_OUT",
  hasCustomRouting: true,
  customRouting: ["email", "push"],
});

let client = CourierClient(jwt: jwt, userId: "user_123")

try await client.preferences.putUserPreferenceTopic(
    topicId: "TOPIC_ID",
    status: .optedOut,
    hasCustomRouting: true,
    customRouting: [.email, .push]
)

val client = CourierClient(jwt = jwt, userId = "user_123")

client.preferences.putUserPreferenceTopic(
    topicId = "TOPIC_ID",
    status = CourierPreferenceStatus.OPTED_OUT,
    hasCustomRouting = true,
    customRouting = listOf(CourierPreferenceChannel.EMAIL, CourierPreferenceChannel.PUSH)
)

final client = CourierClient(jwt: jwt, userId: "user_123");

await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.optedOut,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.email, CourierUserPreferencesChannel.push],
);

import {
  CourierClient,
  CourierUserPreferencesStatus,
  CourierUserPreferencesChannel,
} from "@trycourier/courier-react-native";

const client = new CourierClient({ userId: "user_123", jwt });

await client.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.OptedOut,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.Email, CourierUserPreferencesChannel.Push],
});

Import a full preference set (bulk)

Two bulk endpoints set many topics for a user in one request, up to 50 topics each. They differ in what happens to the topics you don’t send.

Replace makes the body the user’s complete override set. Topics you send are created or updated, and any existing override you leave out is reset to its default. Validation is atomic: one invalid topic fails the whole request.
Update is additive. It touches only the topics you send and processes each independently, returning successes in items and failures in errors.

Send the or bulk request:

import Courier from '@trycourier/courier';

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

const response = await client.users.preferences.bulkReplace('user_123', {
  topics: [
    {
      topic_id: 'pt_01kx4h2jdafq8bk996nn92357r',
      status: 'OPTED_IN',
      has_custom_routing: true,
      custom_routing: ['inbox', 'email'],
    },
  ],
});

console.log(response.deleted);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
response = client.users.preferences.bulk_replace(
    user_id="user_123",
    topics=[{
        "topic_id": "pt_01kx4h2jdafq8bk996nn92357r",
        "status": "OPTED_IN",
        "has_custom_routing": True,
        "custom_routing": ["inbox", "email"],
    }],
)
print(response.deleted)

curl -X PUT https://api.courier.com/users/user_123/preferences \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topics": [ { "topic_id": "pt_01kx4h2jdafq8bk996nn92357r", "status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["inbox", "email"] } ] }'

require "courier"

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

response = courier.users.preferences.bulk_replace(
  "user_123",
  topics: [{status: :OPTED_IN, topic_id: "pt_01kx4h2jdafq8bk996nn92357r"}]
)

puts(response)

response, err := client.Users.Preferences.BulkReplace(
	context.TODO(),
	"user_123",
	courier.UserPreferenceBulkReplaceParams{
		Topics: []courier.UserPreferenceBulkReplaceParamsTopic{{
			TopicID:          "pt_01kx4h2jdafq8bk996nn92357r",
			Status:           "OPTED_IN",
			HasCustomRouting: courier.Bool(true),
			CustomRouting:    []shared.ChannelClassification{shared.ChannelClassificationInbox, shared.ChannelClassificationEmail},
		}},
	},
)

PreferenceBulkReplaceParams params = PreferenceBulkReplaceParams.builder()
    .userId("user_123")
    .addTopic(PreferenceBulkReplaceParams.Topic.builder()
        .status(PreferenceBulkReplaceParams.Topic.Status.OPTED_IN)
        .topicId("pt_01kx4h2jdafq8bk996nn92357r")
        .build())
    .build();
PreferenceBulkReplaceResponse response = client.users().preferences().bulkReplace(params);

$response = $client->users->preferences->bulkReplace(
  'user_123',
  topics: [
    [
      'status' => 'OPTED_IN',
      'topicID' => 'pt_01kx4h2jdafq8bk996nn92357r',
      'customRouting' => [
        ChannelClassification::INBOX, ChannelClassification::EMAIL
      ],
      'hasCustomRouting' => true,
    ],
  ],
);

PreferenceBulkReplaceParams parameters = new()
{
    UserID = "user_123",
    Topics =
    [
        new()
        {
            Status = Status.OptedIn,
            TopicID = "pt_01kx4h2jdafq8bk996nn92357r",
            CustomRouting =
            [
                ChannelClassification.Inbox, ChannelClassification.Email
            ],
            HasCustomRouting = true,
        },
    ],
};

var response = await client.Users.Preferences.BulkReplace(parameters);

courier users:preferences bulk-replace \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --topic '{status: OPTED_IN, topic_id: pt_01kx4h2jdafq8bk996nn92357r}'

Replace is the usual way to bring subscription data from another system into Courier. Send only the topics where a user differs from the default. The rest fall back automatically. Because it is idempotent, you can re-run the import safely, keep users in sync with a source of truth, or resume a backfill mid-loop. Each bulk call covers one user and up to 50 topics, so a backfill iterates your user base. Throttle the loop as you go.

Scope to a tenant

If your app uses , scope any read or write to one Tenant with a tenant_id. On REST that is the ?tenant_id= query parameter. On the SDKs it is the tenant_id argument on any method above. A user’s per-tenant preferences are independent of their global preferences. The read endpoint returns the topic-level default_status, not a tenant’s default preferences, even with a tenant_id. To set what a tenant defaults to, see .

Track preference changes

Courier records each time a user opts in, opts out, or changes a topic’s channels.

Read the change history via API

returns entries newest first. Each is one change to one topic, and previous holds the value it replaced. Pass since for changes from a date or time onward, and user_id for one user’s history. Add tenant_id with user_id to narrow to one tenant.

import Courier from '@trycourier/courier';

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

const changes = await client.workspacePreferences.listLogs({
  since: '2026-09-01',
});

console.log(changes.items);

import os
from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)
changes = client.workspace_preferences.list_logs(
    since="2026-09-01",
)
print(changes.items)

curl -X GET "https://api.courier.com/preferences/logs?since=2026-09-01" \
  -H "Authorization: Bearer $COURIER_API_KEY"

require "courier"

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

changes = courier.workspace_preferences.list_logs(since: "2026-09-01")

puts(changes)

changes, err := client.WorkspacePreferences.ListLogs(
	context.TODO(),
	courier.WorkspacePreferenceListLogsParams{
		Since: courier.String("2026-09-01"),
	},
)

PreferenceLogsListResponse changes = client.workspacePreferences().listLogs(
    WorkspacePreferenceListLogsParams.builder()
        .since("2026-09-01")
        .build()
);

$changes = $client->workspacePreferences->listLogs(since: '2026-09-01');

WorkspacePreferenceListLogsParams parameters = new() { Since = "2026-09-01" };

var changes = await client.WorkspacePreferences.ListLogs(parameters);

courier workspace-preferences list-logs \
  --api-key "$COURIER_API_KEY" \
  --since 2026-09-01

A page holds 25 entries by default and up to 100 with limit. While paging.more is true, pass paging.cursor back as cursor to get the next page. The endpoint allows one request every two seconds, so fetch pages one at a time.

Receive changes as webhook events

Courier also sends each change to your as a preferences:user:updated . Its data is the same entry the change history returns, with the same id, so you can match an event to its entry.

Mirror preferences in another system

To keep a copy of users’ choices in your CRM or database:

Load each user’s current preferences with .
Apply each preferences:user:updated event as it arrives.
After your endpoint has been down, read the change history with since set to the last timestamp you applied. Apply the entries oldest first, and skip any id you’ve already applied.

Resetting a topic to its default removes the user’s override, so it doesn’t add an entry or send an event. That includes calls to and the topics a bulk replace lists in deleted. Apply those resets to your copy when your code makes the calls.

Verify

Update a topic and read it back

Update a topic to OPTED_OUT, then and confirm the status.

Confirm the send is blocked

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

Re-run an import

For an import, re-run the same bulk replace and confirm the result is unchanged (it is idempotent).

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Manage user preferences with the API

Prerequisites

Read a user’s preferences

Update one topic

Client SDKs

Import a full preference set (bulk)

Scope to a tenant

Track preference changes

Read the change history via API

Receive changes as webhook events

Mirror preferences in another system

Verify

​Prerequisites

​Read a user’s preferences

​Update one topic

​Client SDKs

​Import a full preference set (bulk)

​Scope to a tenant

​Track preference changes

​Read the change history via API

​Receive changes as webhook events

​Mirror preferences in another system

​Verify

Prerequisites

Read a user’s preferences

Update one topic

Client SDKs

Import a full preference set (bulk)

Scope to a tenant

Track preference changes

Read the change history via API

Receive changes as webhook events

Mirror preferences in another system

Verify