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. Call the :

Where custom routing over the API is not 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 do not 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. There is no across-users endpoint, so a backfill means iterating your user base with one bulk call per user (max 50 topics each). 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 .

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

Verify

​Prerequisites

​Read a user’s preferences

​Update one topic

​Client SDKs

​Import a full preference set (bulk)

​Scope to a tenant

​Verify

Prerequisites

Read a user’s preferences

Update one topic

Client SDKs

Import a full preference set (bulk)

Scope to a tenant

Verify