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.

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.