Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Use the User Preferences API to manage notification preferences from your backend. This tutorial covers reading and updating preferences programmatically; for setting up subscription topics and surfacing preferences to users, see:

​
Prerequisites

​
Required Parameters

Every preference update needs two identifiers:
  • user_id - The recipient’s unique ID (same ID used in send requests)
  • topic_id - The subscription topic ID, found in the Preferences Editor

​
Read a User’s Preferences

Fetch all preferences for a user to see their current opt-in/out status across all topics: 
curl -X GET https://api.courier.com/users/{user_id}/preferences \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

​
Update a Topic Preference

Set a user’s opt-in status for a specific topic. The topic object requires a status field with one of these values:
StatusBehavior
OPTED_INUser receives notifications for this topic
OPTED_OUTUser does not receive notifications for this topic
REQUIREDUser cannot opt out (use for critical notifications like security alerts)
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"
    }
  }'

​
Custom Routing (Enterprise)

Enterprise customers can set channel delivery preferences per topic. For example, if a notification template has email, SMS, and push channels, you can let a user receive only email: 
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.

​
Tenant-Scoped Preferences

If your app uses tenants, pass a tenant_id to read or write preferences scoped to a specific tenant: 
curl -X GET "https://api.courier.com/users/{user_id}/preferences?tenant_id=tenant_abc" \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

​
What’s Next

Set Up Hosted Preferences

Deploy a hosted preference page for your users

Embed Preferences in React

Build an in-app preference center with React components

Preferences Editor

Configure topics, sections, and channel options

User Preferences API

Full API reference