Sitecore Experience Manager

The List Manager API

Sitecore stores contact lists as marketing definitions. On a Content Manager (CM) instance, you can access contact lists programmatically with the List Manager API.

Note

You cannot use the List Manager API on a Content Delivery (CD) instance because the List Manager application is disabled in this case.

This topic contains code samples for the following tasks:

Important

The code snippets in this topic apply to Sitecore 9.0.1 and later. The table below lists the equivalent commands for Sitecore 9.0.

Sitecore 9.0.1 and later

Sitecore 9.0

GetService<IFetchRepository<SegmentModel>>()

GetService<SegmentRepository>()

GetService<IFetchRepository<SegmentedListModel>>()

GetService<SegmentedListRepository>()

GetService<IFetchRepository<ContactListModel>>()

GetService< ContactListRepository>()

This example shows you how to add a segment using the List Manager API.

Note

The creation and modification of the segment rules can only be done through the List Manager interface.

var segmentRepository = ServiceLocator.ServiceProvider.GetService< SegmentRepository>();

var newSegment = new SegmentModel
      {
         Id = Guid.NewGuid().ToString("B"),
         Name = "New Segment",
         Description = "New Description",
         UseAsAnalyticsFilter = true
      };

segmentRepository.Add(newSegment);

This example shows you how to update a segment.

var segmentRepository = ServiceLocator.ServiceProvider.GetService< SegmentRepository>();

//Find existing segment by ID. ID must be vali
var segmentToUpdate =  segmentRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentToUpdate.Description = "New Description";
segmentRepository.Update(segmentToUpdate);

This example shows you how to delete a segment.

var segmentRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository<SegmentModel>>();

//Find existing segment by ID. ID must be valid.

var segmentToDelete =  segmentRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentRepository.Delete(segmentToDelete);

This example shows you how to add a segmented list.

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService< SegmentedListRepository>();

var newSegmentedList = new SegmentedListModel()
            {
                Id = Guid.NewGuid().ToString("B"),
                Name = "New Contact List",
                Description = "Description of the contact list",
                Owner = "Administrator"
            };

To add segments to the list you want to create, use this code snippet.

newSegmentedList .SegmentIds = new[] {“<Guid of the Segment>”};

To save the new segmented list, use this code snippet.

segmentedListRepository.Add(newSegmentedList);

This example shows you how to update a segmented list.

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService< SegmentedListRepository>();

//Find existing list by ID. ID must be valid.

var listToUpdate =  segmentedListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
listToUpdate.Description = "New Description";
segmentedListRepository.Update(listToUpdate);

This example shows you how to delete a segmented list.

var segmentedListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository<SegmentedListModel>>();

//Find existing list by ID. ID must be valid.

var listToDelete =  segmentedListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
segmentedListRepository.Delete(listToDelete);

This example shows you how to add a contact list.

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();
var newContactList = new ContactListModel()
       {
           Id = Guid.NewGuid().ToString("B"),
           Name = "New Contact List",
           Description = "Description of the contact list",
           Owner = "Administrator"
        };

To add an included list to the one you want to create, use this code snippet.

newContactList.Subscriptions.Add(new SubscriptionViewModel
            {
               Id = Guid.NewGuid(),
               ListId = <Guid of the List>, 
               Name= "Name of the included list"
            });

To save the new contact list, use this code snippet.

contactListRepository.Add(newContactList);

This example shows you how to update a contact list.

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();

//Find existing list by ID. ID must be valid.
var listToUpdate =  contactListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
listToUpdate.Description = "New Description";
contactListRepository.Update(listToUpdate);

This example shows you how to delete a contact list.

var contactListRepository = ServiceLocator.ServiceProvider.GetService<IFetchRepository< ContactListModel>>();

//Find existing list by ID. ID must be valid.

var listToDelete =  contactListRepository.FindById("{00000000-0000-0000-0000-000000000000}");
contactListRepository.Delete(listToDelete);

This example shows you how to add one contact to a contact list:

var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Subscribe(contactListId, contactId);

This example shows you how to add multiple contacts to a contact list:

var contacts = new List<Contact>(); // List of contacts
var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Subscribe(contactListId, contacts);

To remove a contact association and call the corresponding methods from ISubscriptionService:

var subscriptionService = ServiceLocator.ServiceProvider.GetService<ISubscriptionService>();
subscriptionService.Unsubscribe(contactListId, contactId);
subscriptionService.Unsubscribe(contactListId, contacts);

This example shows how you retrieve contacts from a contact list:

int batchSize = 200; // Size of the batch
string[] facets =
{
    CollectionModel.FacetKeys.PersonalInformation,    
    CollectionModel.FacetKeys.ListSubscriptions
}; // Contact facets to retrieve
var contactListProvider = ServiceLocator.ServiceProvider.GetService<IContactListProvider>();
var contactProvider = ServiceLocator.ServiceProvider.GetService<IContactProvider>();
var contactList = contactListProvider.Get(contactListId, cultureInfo);
var contactBatchEnumerator = contactProvider.GetContactBatchEnumerator(
    contactList,     
    batchSize,
     facets);
while (contactBatchEnumerator.MoveNext())
{    
var contacts = contactBatchEnumerator.Current;
    // write your logic here
    contacts.ToList();
}

The example uses a batch enumerator as the most efficient and the fastest way to iterate over contacts. See the xConnect documentation for more information.