Area: Optimizely CMS
Applies to versions: 12 and higher
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Subscription keys

Recommended reading 
Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.

This topic describes the subscription keys for the User Notifications framework used for  sending user-to-user notification messages in Optimizely.

How it works

This API supports storing a link between a key and an user. You can then later use the API to get a list of users subscribing to a key. A key can be anything you want formatted as an URI.

Access the API by getting an instance of the ISubscriptionService interface, with which you can subscribe or unsubscribe a user and find users that subscribe to a particular key.

This API is just a supporting service and subscriptions are independent from user notifications, no calls are made from one to the other. That means you need to use the subscriptions API to populate the recipient field when creating a notification message because an event happened in the system. If the sender is also a subscriber you may need to filter the list before sending the message to avoid that the person triggering the event also gets notified.

Subscription keys

A subscription key is in URI format and identifies something that can be notified. The format is unconstrained but should match the item it identifies.

The subscription key indicates that the user is interested in that item and items below it; that is, all items that have a key that starts with the subscribed key.

Subscribe and unsubscribe

Use the SubscribeAsync methods to add one or more users to a subscription.

Use the UnsubscribeAsync method to remove one or more users from a subscription.

You can hook into the UserSubscribed and UserUnsubscribed events. They only are triggered for changes. If a user is added to a subscription twice, it only triggers for the first.


By calling ClearUserAsync, subscriptions for that user are removed so use it only when you delete a user from the system. The ClearSubscriptionAsync method removes users from that particular subscription. The UserCleared and SubscriptionCleared events are called for these respectively.

List subscriptions

ListSubscriptionsAsync returns a list of subscriptions for a user.

List and find subscribers

ListSubscribersAsync returns a list of users that subscribe to a specified subscription. The FindSubscribersAsync method returns users that match a subscription key, fully and partly (begins-with).

Note: The partly matching is done on whole segments (delimited by slashes) in the URI path.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021

Recommended reading