1. Subscription management

The Email Experience Manager Client API

Version:

The Email Experience Manager ClientAPI class, Sitecore.Modules.EmailCampaign.ClientAPI, is used by EXM to handle subscribes and unsubscribes. You can use it to manage subscriptions to lists in the List Manager and send automated email messages.

Note

The methods on the Email Experience Manager ClientAPI class are static. It is important that you use these static methods and not, for example, the instance methods on ClientApiLocal, Sitecore.Modules.EmailCampaign.Core.ClientApiLocal.

In scaled server setups with, for example, dedicated Content Delivery (CD) and Content Management (CM) instances, the CD server is not configured to add or remove contacts from a List Manager list, or to send EXM campaigns. Therefore, the ClientAPI request must be forwarded to the CM server.

The Client API looks for the EmailCampaignClientService connection string to determine if the request can be carried out locally on the server or if the request must be forwarded to a CM instance.

The following diagram depicts this process:

Methods

You can use the following public methods to manage the subscriptions:

These methods use a RecipientId to identify the contact that you want to change the subscription for. You can get the contact ID in several ways. For example:

  • To get the contact ID of the currently identified contact:

    // Get the id of the currently identified contact. See https://doc.sitecore.net/sitecore_experience_platform/setting_up_and_maintaining/xdb/contacts/identifying_contacts
var contactId = Tracker.Current.Contact.ContactId

  • To get the contact ID when you only know the contact identifier:

    // The identifier of the contact to get the contact id from. See https://doc.sitecore.net/sitecore_experience_platform/setting_up_and_maintaining/xdb/contacts/identifying_contacts
var contactIdentifier = [email protected];
var contactRepository = (ContactRepositoryBase)Configuration.Factory.CreateObject(“contactRepository”, true);
//Load the contact in read-only mode.
var contact = contactRepository.LoadContactReadOnly(contactIdentifier);
var contactId = contact.ContactId;

TrySubscribe

bool TrySubscribe(RecipientId recipientId, Guid messageId, bool subscriptionConfirmation)

This method adds the contact (recipientId) to the first non-segmented include list defined on the campaign (messageId). If subscriptionConfirmation is set, EXM sends a confirmation email message to the contact, asking them to confirm the subscription before adding them to the list.

In addition, the contact is also removed from the default global opt-out list.

Note

You can extend this functionality by implementing the SubscribeEvent pipeline. See The EXM extensibility points.

Example:

var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
var messageId = new Guid(“6e4ad96c-1856-4bb0-95e2-c35d2e2d0734”);
var isSubscribed = ClientApi.TrySubscribe(recipientId, messageId, false);

Unsubscribe

string Unsubscribe(RecipientId recipientId, Guid messageId)

This method removes the contact (recipientId) from all the contact lists that are included in the email campaign (messageId).

The method returns the path that is specified on the Final Confirmation Page setting of the Manager Root item. If the path is not specified, the Home Page path is returned.

If the unsubscribing fails, for example, if the contact is not on the list, the API returns the path that is specified for the Already Unsubscribed Page. If the contact is successfully unsubscribed from a list, EXM sends the notification that is defined by the StandardMessages.UnsubscribeNotification setting to the contact.

If the contact could not be removed from any included contact lists or if the contact does not appear in any of the lists, the contact is instead added to the global opt-out list that is defined on the manager root.

Note

You can extend the functionality, if you implement the UnsubscribeEvent pipeline. See The EXM extensibility points.

Example:

var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
var messageId = new Guid(“6e4ad96c-1856-4bb0-95e2-c35d2e2d0734”);
var redirectUrl = ClientApi.Unsubscribe(recipientId, messageId);
Response.Redirect(redirectUrl ?? "/", false);

UnsubscribeFromAll

string UnsubscribeFromAll(RecipientId recipientId, Guid messageId)

This method adds the contact (recipientId) to the global opt-out list that is defined on the email campaign's (messageId) manager root. If the contact is added to the global opt-out list, a notification that is defined by the StandardMessages.UnsubscribeFromAllNotification setting is sent to the contact.

The method returns the path to the Final Confirmation Page. If the setting is not specified, the path to the Home Page is returned.

If the contact cannot be removed, for example, if the contact is already in the global opt-out list, the path to the Already Unsubscribed Page is returned.

Note

You can extend the functionality, if you implement the UnsubscribeFromAllEvent pipeline. See The EXM extensibility points.

Example:

var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
var messageId = new Guid(“6e4ad96c-1856-4bb0-95e2-c35d2e2d0734”);
var redirectUrl = ClientApi.UnsubscribeFromAll(recipientId, messageId);
Response.Redirect(redirectUrl ?? "/", false);

UpdateSubscriptions

string UpdateSubscriptions(RecipientId recipientId, string[] listsToSubscribe, string[] listsToUnsubscribe, string managerRootId, bool confirmSubscription)

This method adds the contact (recipientId) to all the List Manager lists in listsToSubscribe, and removes the contact from all List Manager lists in listsToUnsubscribe.

The method returns the path, defined on the manager root (managerRootId), to either the Email Sent Confirmation Page setting or the Final Confirmation Page setting that is defined on the manager root, depending on whether confirmSubscribtion is set and whether the contact is already subscribed to any lists.

Note

Contacts are added or removed in a similar way to how it is handled in the TrySubscribe and the Unsubscribe methods.

Example:

var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
string managerRootId = "de826df7-69db-4c3b-87de-782432263c77";
string[] listsToSubscribe =
{
"c0549793-893a-44d1-a616-a02dd5f58dee",
"aaf9456d-fa33-45d5-bc8d-d10d979ca049",
"d2e4eda8-b34b-4861-8290-646a76516baf"
};
string[] listsToUnsubscribe =
{
"3086d63a-377a-4f86-8c57-99650472d8ca",
"ae5b1567-7678-487e-b3a5-5c28fcfcc85a",
"abf5ec21-eeae-4401-855c-5b393256cf1b"
};
var redirectUrl = ClientApi.UpdateSubscriptions(recipientId, listsToSubscribe, listsToUnsubscribe, managerRootId, false);
Response.Redirect(redirectUrl ?? "/", false);
Note

For more information, see Identifying contacts.

RemoveUserFromGlobalOptOutList

void RemoveUserFromGlobalOptOutList(RecipientId recipientId, Guid managerRootId)

This method removes the contact (recipientId) from the global opt-out list defined on the manager root (managerRootId).

Example:

var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
var managerRootId = new Guid("de826df7-69db-4c3b-87de-782432263c77");
ClientApi.RemoveUserFromGlobalOptOutList(recipientId, managerRootId);

SendStandardMessage

void SendStandardMessage(Guid messageId, RecipientId recipientId, bool async, IDictionary<string, object> customPersonTokens = null)

This method sends an activated automated email campaign (messageId) to the contact (recipientId) using either an asynchronous (async == true) or a synchronous sending manager with the option to specify a set of custom tokens.

Example:

var tokens = new Dictionary<string, object>
{
    {"tokenKey", 123},
    {"anotherTokenKey", "some token value"},
};
var messageId = new Guid("c896a148-921c-4b36-8f60-9b2d0b03ba60");
var recipientId = new XdbContactId(Tracker.Current.Contact.ContactId);
ClientApi.SendStandardMessage(messageId, recipientId, true, tokens);
If you have suggestions for improving this article, let us know!