Skip to main content
With Courier’s Preferences API users can create and update their recipients’ delivery preferences through an API call.

​
Understanding User Preferences

User Preferences gives your users the ability to control which notification topics they receive, through the channels of their choice. This feature is designed to give your users control over their communication preferences and to help you comply with data privacy regulations like GDPR and CCPA. Your users can set their own preferences through the preferences hosted page, or they can be manually updated through the API.

​
Configuring User Preferences

To create or edit a user’s preference, you will need to gather some important keys for the path parameters:
  • The recipient’s unique user_id that preferences are attached to.
  • The preference subscription topic_id that can be found in the preferences editor.

​
Configuring the Request Body

The preference request must contain a topic object with a required status parameter. One of the following statuses are required for each preference call made to a topic:
  • opted_in - The user is opted in to the topic and any notifications mapped to it.
  • opted_out - The user is opted out of the topic and its corresponding notifications.
  • required - The user cannot opt out of this topic and its notifications.
A sample request to the preferences endpoint looks like this: 
// PUT https://api.courier.com/users/:user_id/preferences/:topic_id
{
	"topic": {
		"status": "OPTED_IN" // This field is required
	}
}

​
Preferences and Custom Routing

For Courier customers on the Enterprise plan, you have the ability to set a custom_routing object for your recipients. This object translates to channel delivery customization in the Preferences Center. This configuration sets a specific channel delivery preference for each user. For example if a notification had 3 delivery channels (email, sms, push) and the recipient only wanted email, a request could be shaped like so: 
// PUT https://api.courier.com/users/:user_id/preferences/:topic_id
{
	"topic": {
		"status": "OPTED_IN", // This field is required
        "has_custom_routing": true, // Available for business tier only
		"custom_routing": [
			"email"
		]
	}
}
Please note that for custom_routing to work, the notification template must have multiple delivery channels configured and be part of a subscription topic.