Manage Lists

Create, organize, and manage contact lists to segment your audience for targeted email campaigns.

Goal

By the end of this guide you will be able to create lists within a contact structure, list all existing lists, update list names, delete lists, duplicate a list, and merge multiple lists into one.

Prerequisites

An API key with contacts:write scope (for full list management) or contacts:read scope (for read-only access)
Your API base URL (found on the Settings > API Keys page)
A contact structure ID — lists belong to a contact structure. Retrieve yours with GET /api/contact-structure (see Manage Custom Fields)

Steps

1. Create a list

Create a new list within a contact structure. The only required field is name.

curl -X POST "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers"
  }'

Response (201 Created):

{
  "_id": "66f1a6e4698f1bca60425001",
  "name": "Newsletter Subscribers",
  "type": "static",
  "createdAt": "2026-03-28T14:30:00.000Z",
  "updatedAt": "2026-03-28T14:30:00.000Z",
  "__v": 0
}

Notes:

List type defaults to "static" (the only supported type currently)
List names can be up to 1,000 characters

2. List all lists (paginated)

Retrieve lists with pagination, sorting, and search support.

curl "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists?page=1&size=25&sort=name:asc" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"

Response (200 OK):

{
  "total": 2,
  "records": [
    {
      "_id": "66f1a6e4698f1bca60425001",
      "name": "Newsletter Subscribers",
      "type": "static",
      "totalContacts": 1250,
      "totalCampaigns": 3,
      "createdAt": "2026-03-28T14:30:00.000Z",
      "updatedAt": "2026-03-28T14:30:00.000Z",
      "__v": 0
    },
    {
      "_id": "66f1a6e4698f1bca60425002",
      "name": "VIP Customers",
      "type": "static",
      "totalContacts": 85,
      "totalCampaigns": 7,
      "createdAt": "2026-03-20T10:00:00.000Z",
      "updatedAt": "2026-03-25T16:45:00.000Z",
      "__v": 1
    }
  ]
}

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (1-indexed)
`size`	integer	Number of results per page
`sort`	string	Sort field and direction, e.g. `name:asc`, `createdAt:desc`
`criteria`	string	Search filter text to match list names

To retrieve all lists without pagination (returns _id, name, and type only):

curl "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/all" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"

3. Get a single list

curl "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"

Response (200 OK):

{
  "_id": "66f1a6e4698f1bca60425001",
  "name": "Newsletter Subscribers",
  "type": "static",
  "createdAt": "2026-03-28T14:30:00.000Z",
  "updatedAt": "2026-03-28T14:30:00.000Z",
  "__v": 0
}

4. Update a list

Rename a list by sending a PATCH request. You must include the current __v (version) value for optimistic concurrency control.

curl -X PATCH "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Newsletter",
    "__v": 0
  }'

Response (200 OK):

{
  "_id": "66f1a6e4698f1bca60425001",
  "name": "Monthly Newsletter",
  "type": "static",
  "createdAt": "2026-03-28T14:30:00.000Z",
  "updatedAt": "2026-03-28T15:00:00.000Z",
  "__v": 1
}

Important: The __v field prevents conflicts when multiple clients update the same list. Always send the current __v value from your last GET response. If another update occurred in the meantime, you will receive a 400 error with a ConcurrencyError type.

5. Delete a list

Delete a single list by ID:

curl -X DELETE "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"

Response (204 No Content): Empty body. To delete multiple lists at once, send a DELETE to the lists collection endpoint:

curl -X DELETE "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v" \
  -H "Content-Type: application/json" \
  -d '{
    "listIds": [
      "66f1a6e4698f1bca60425001",
      "66f1a6e4698f1bca60425002"
    ]
  }'

Response (204 No Content): Empty body.

6. Duplicate a list

Create a copy of an existing list (contacts are copied to the new list).

curl -X POST "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001/duplicate" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers (Copy)"
  }'

Response (201 Created):

{
  "_id": "66f1a6e4698f1bca60425003",
  "name": "Newsletter Subscribers (Copy)",
  "type": "static",
  "createdAt": "2026-03-28T16:00:00.000Z",
  "updatedAt": "2026-03-28T16:00:00.000Z",
  "__v": 0
}

7. Merge lists

Combine two or more lists into a new list. Contacts from all source lists are added to the new list (duplicates are handled automatically).

curl -X POST "<your-api-base-url>/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/merge" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Subscribers (Merged)",
    "listIds": [
      "66f1a6e4698f1bca60425001",
      "66f1a6e4698f1bca60425002"
    ]
  }'

Response (200 OK):

{
  "_id": "66f1a6e4698f1bca60425004",
  "name": "All Subscribers (Merged)",
  "type": "static",
  "createdAt": "2026-03-28T16:30:00.000Z",
  "updatedAt": "2026-03-28T16:30:00.000Z",
  "__v": 0
}

Notes:

The source lists are not deleted; they remain intact
The merged list is a new list containing all unique contacts from the source lists
At least one listId is required

Common Errors

Status	Error	Cause	Fix
`401`	`UnauthorizedError`	Invalid or inactive API key	Verify your key in Settings > API Keys
`403`	`ForbiddenError`	Key lacks `contacts:write` scope	Upgrade the key’s scopes or create a new key with `contacts:write`
`400`	`ValidationError`	Missing required fields (e.g., `name`)	Check request body against the schema requirements
`400`	`ConcurrencyError`	`__v` mismatch on update — another update occurred since your last read	Fetch the latest version with GET and retry with the current `__v`
`404`	`RecordNotFound`	Contact structure ID or list ID does not exist	Verify IDs match existing resources
`429`	`TooManyRequestsError`	Rate limit or monthly quota exceeded	Wait for the `Retry-After` period. See Rate Limits

Next Steps

Manage Contacts — create contacts and assign them to lists
Search Contacts — find contacts within a specific list
Manage Custom Fields — define the fields on your contact structure
Migration from Legacy — end-to-end data migration workflow

Get Started

Scenarios

Goal

Prerequisites

Steps

1. Create a list

2. List all lists (paginated)

3. Get a single list

4. Update a list

5. Delete a list

6. Duplicate a list

7. Merge lists

Common Errors

Next Steps

​Goal

​Prerequisites

​Steps

​1. Create a list

​2. List all lists (paginated)

​3. Get a single list

​4. Update a list

​5. Delete a list

​6. Duplicate a list

​7. Merge lists

​Common Errors

​Next Steps

Goal

Prerequisites

Steps

1. Create a list

2. List all lists (paginated)

3. Get a single list

4. Update a list

5. Delete a list

6. Duplicate a list

7. Merge lists

Common Errors

Next Steps