EmailSendX Docs
EmailSendX Docs
/
Docs/API Reference/Lists

Lists API

Lists are static, named groups of contacts. Create and manage lists via the API, then assign contacts to them during upsert or bulk import operations.

The List Object

A list is a named, static group of contacts within a workspace. Unlike segments (which are dynamic and filter-based), lists are manually managed — contacts are added and removed explicitly.

json
{
  "id": "clx_list_example_id",
  "name": "Newsletter Subscribers",
  "description": "Main newsletter list — opted-in via website signup form",
  "memberCount": 4820,
  "createdAt": "2026-01-10T09:00:00Z",
  "updatedAt": "2026-01-20T14:00:00Z"
}
FieldTypeDescription
idstringUnique list identifier (CUID)
namestringHuman-readable list name
descriptionstringOptional description of the list's purpose
memberCountintegerCurrent number of active contacts in the list
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-update timestamp

Endpoints

All list endpoints require the lists:read or lists:write scope.

List All Lists

GET/api/v1/listsscope: lists:read

Returns a paginated list of all lists in the workspace. Optionally retrieve a single list by its ID using the id query parameter.

Parameters

NameTypeInRequiredDescription
pageintegerqueryoptionalPage number (default: 1)
limitintegerqueryoptionalResults per page, max 100 (default: 50)
idstringqueryoptionalReturn a single list by its ID

Response

json
{
  "data": [
    {
      "id": "clx_list_newsletter_id",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter list",
      "memberCount": 4820,
      "createdAt": "2026-01-10T09:00:00Z",
      "updatedAt": "2026-01-20T14:00:00Z"
    },
    {
      "id": "clx_list_customers_id",
      "name": "Paying Customers",
      "description": "All users with an active subscription",
      "memberCount": 1247,
      "createdAt": "2026-01-12T11:30:00Z",
      "updatedAt": "2026-04-20T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 8,
    "totalPages": 1
  }
}

Create a List

Create a new list in the workspace. After creating a list, you can add contacts to it by passing the list ID in the listId field when upserting contacts.

POST/api/v1/listsscope: lists:write

Create a new contact list. Returns the newly created list object.

Parameters

NameTypeInRequiredDescription
namestringbodyrequiredList name (must be unique within the workspace)
descriptionstringbodyoptionalOptional description for internal documentation

Request Body

json
{
  "name": "Beta Testers",
  "description": "Users enrolled in the beta program — signed up via /beta page"
}

Response

json
{
  "data": {
    "id": "clxnew_list_beta_id",
    "name": "Beta Testers",
    "description": "Users enrolled in the beta program — signed up via /beta page",
    "memberCount": 0,
    "createdAt": "2026-04-22T10:00:00Z",
    "updatedAt": "2026-04-22T10:00:00Z"
  }
}

Adding contacts to a list

After creating a list, add contacts by including listId in the body of a POST /contacts or POST /contacts/bulk request. See the Contacts API for details.

Ready to organize your audience?

Create lists via API and assign contacts during upsert to keep your audience organized.

View Contacts APIExplore segments