---
title: "Contact lists"
slug: "contact-lists"
abstract: ""
---
# Contact lists

Contact list definitions are managed by the `Sitecore.Marketing.Definitions.ContactLists.ContactListDefinitionManager` class.

## Accessing the ContactListDefinitionManager

The `ContactListDefinitionManager` is available from the Sitecore DI container. It is preferable to include a parameter of type `DefinitionManagerBase<IContactListDefinition, ContactListDefinitionRecord>` in the constructor of your class and pull your class from the container, allowing the container to resolve the instance for you:

```csharp
public MyClass(DefinitionManagerBase<IContactListDefinition, ContactListDefinitionRecord> contactListDefinitionManager)
{
        ...
}

```

If you cannot use the container to construct your class, you can use the service locator. This class is also available in the Sitecore DI container:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

```

## Defining a contact list

A contact list is defined using types from the `Sitecore.Marketing.Definitions.ContactLists` namespace.

```csharp
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Documentation
{
    public class AddContactList
    {
        public void Example()
        {
            Guid contactListId = Guid.NewGuid(); // Contact list ID
            CultureInfo contactListCulture = new CultureInfo("es"); // Contact list culture
            string contactListName = "Newly created contact list"; // Contact list name
            DateTime creationDate = DateTime.UtcNow; // Contact list creation date
            string createdBy = "sitecore\admin"; // Contact list creator

            ContactListDefinition contactList = new ContactListDefinition(contactListId, "Contact list item name", contactListCulture, contactListName, creationDate, createdBy);

            contactList.Owner = "sitecore\\maw";
            contactList.Type = "Folder";
        }
    }
}

```

> [!important]
> All `ContactListDefinition` properties except `Type` and `Owner` have been marked obsolete but not removed - this is to support migration for components such as List Manager. Be aware that some properties might be removed or moved in later releases.

## Saving a contact list

Once you have defined a contact list you may save it by calling the `SaveAsync()` method on the definition manager.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class SaveContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID
                        CultureInfo contactListCulture = new CultureInfo("es"); // Contact list culture
                        string contactListName = "Newly created contactList"; // Contact list name
                        DateTime creationDate = DateTime.UtcNow; // Contact list creation date
                        string createdBy = "sitecore\admin"; // Contact list creator

                        ContactListDefinition contactList = new ContactListDefinition(contactListId, "Contact list item name", contactListCulture, contactListName, creationDate, createdBy);

                        contactList.Owner = "sitecore\\maw";
                        contactList.Type = "Folder";

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        await manager.SaveAsync(contactList);
                }
        }
}

```

You can also optionally activate the contact list during save by passing `true` to the second parameter of the `SaveAsync()` method:

```text
manager.SaveAsync(contactList, true);

```

## Activating a contact list

Contact lists must be activated before they are available for use outside of Experience Manager. Contact lists can be activated when they’re saved by passing `true` to the `activate` (second) parameter of the `SaveAsync()` method:

```text
manager.SaveAsync(contactList, true);

```

Contact lists can also be activated without calling save, using the `ActivateAsync()` method:

```text
manager.ActivateAsync(contactListId);

```

The `ActivateAsync()` method takes the ID of the contact list and does not require the contact list definition model.

## Deleting a contact list

To delete a contact list, use the `Delete()` method on the manager. Individual cultures cannot be deleted from the definition, only the entire definition. The culture provided to the method call should be either null (default value) or `CultureInfo.InvariantCulture`.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class SaveContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        manager.Delete(contactListId);
                }
        }
}

```

## Get a contact list

A single contact list can be retrieved by its ID using one of the `Get()` methods on the manager.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class GetContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        manager.Get(contactListId, new CultureInfo("en"), true);
                }
        }
}

```

### Retrieve a contact list by its alias

You can also retrieve a contact list by its [alias](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-platform/definition-aliases.html "Definition aliases"):

```csharp
CultureInfo contactListCulture = new CultureInfo("fr-fr");
var contactListDefinitionByAlias = definitionManager.GetByAlias("My alias", contactListCulture);

```

## Update an existing contact list

To update an existing contact list definition, retrieve the contact list by ID, edit the contact list properties, and save/activate to use:

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

namespace Documentation
{
        public class UpdateContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        var contactList = manager.Get(contactListId, new CultureInfo("en"), true);

                        contactList.Owner = "sitecore\\newowner";
                        contactList.Name = "New name";

            manager.SaveAsync(contactList, true);
                }
        }
}

```

## Retrieving all contact lists

The `.GetAll()` method can be used to get all contact lists from the manager. As there may be a large number of definitions, this method supports paging. The return value is a single page of results.

```csharp
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions.ContactLists;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Sitecore.Marketing.Definitions;
using Sitecore.Marketing.Core;

namespace Documentation
{
        public class GetAllContactList
        {
                public async void Example()
                {
                        Guid contactListId = Guid.NewGuid(); // Contact list ID

                        IDefinitionManager<IContactListDefinition> manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IContactListDefinition>();

                        // Get 'en' contact list, including inactive versions
                        var contactList = manager.Get(contactListId, new CultureInfo("en"), true);

                        // Get All with defaults which will be first page, page size 20, latest active versions only
                        ResultSet<DefinitionResult<IContactListDefinition>> contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>());

                        // Get page 2
                        ResultSet<DefinitionResult<IContactListDefinition>> page2contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>(pageNumber: 2));

                        // Include inactive versions
                        ResultSet<DefinitionResult<IContactListDefinition>> page1contactLists = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IContactListDefinition, string>(), true);
                }
        }
}

```

To access the results, use the `DataPage` property of the result.

```text
IContactListDefinition contactList = page1contactLists.DataPage.ElementAt(0);

```

The result also includes properties to expose the total number of definitions and the current page index and page size.

```

long totalDefinitionCount = contactLists.Total;
int pageNumber = page1contactLists.PageNumber;
int pageSize = contactLists.Count;

```