Email Experience Manager

The Email Experience Manager Client API

Abstract

Use the Email Experience Manager Client API to manage subscriptions.

The Email Experience Manager ClientAPIService class, Sitecore.EmailCampaign.Cd.Services.ClientAPIService, 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.

The ClientApiService is registered in the IOC container, so you can either inject it into the constructor of your class or you can use the ServiceLocator, for example:

IClientApiService _clientApiService;public MyConstructor(IClientApiService clientApiService)
{
  _clientApiService = clientApiService;
}

or

IClientApiService clientApiService = ServiceLocator.ServiceProvider.GetService< IClientApiService >()

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, you must use the ClientAPIService request to delegate that work to the CM servers.

The following diagram depicts this process:

4C9A838191FE420CA635418EF0562CEF.png

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

  • Subscribe

  • Unsubscribe

  • SendAutomatedMessage

These methods use a ContactIdentifier to identify the contact that you want to do the operation. For more information, see   Contact identifiers and Identifying contacts.Contact identifiersIdentifying contacts

Subscribe

Subscribe(SubscribeMessage subscribeMessage)

This method adds the contact (subscribeMessage.ContactIdentifier) to the first non-segmented include list defined on the campaign (subscribeMessage.MessageId). If subscribeMessage.RequireSubscriptionConfirmation 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 the functionality by implementing the SubscribeEvent pipeline.

Unsubscribe

Unsubscribe(UnsubscribeMessage unsubscribeMessage) 

If AddToGlobalOptOutList (unsubscribeMessage.addToGlobalOptOutList) is true, the contact is added to the global opt-out list that is defined on the email campaign's (unsubscribeMessage.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.

If AddToGlobalOptOutList (unsubscribeMessage.addToGlobalOptOutList) is false, this method removes the contact (unsubscribeMessage.ContactIdentifier) from all the contact lists that are included in the email campaign (unsubscribeMessage.MessageId). 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 or the UnsubscribeFromAllEvent pipeline.

SendAutomatedMessage

void SendAutomatedMessage(AutomatedMessage automatedMessage)  

This method sends an activated automated email campaign (automatedMessage.MessageId) to the contact (automatedMessage.ContactIdentifier) with the option to specify a set of custom tokens and the target language.