> ## Documentation Index
> Fetch the complete documentation index at: https://developers.benchmarkemail.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage lists

# 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](./manage-custom-fields.md))

## Steps

### 1. Create a list

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

```bash theme={null}
curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers"
  }'
```

**Response** (`201 Created`):

```json theme={null}
{
  "_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.

```bash theme={null}
curl "https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists?page=1&size=25&sort=name:asc" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`200 OK`):

```json theme={null}
{
  "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):

```bash theme={null}
curl https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/all \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

### 3. Get a single list

```bash theme={null}
curl https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001 \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`200 OK`):

```json theme={null}
{
  "_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.

```bash theme={null}
curl -X PATCH https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001 \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Newsletter",
    "__v": 0
  }'
```

**Response** (`200 OK`):

```json theme={null}
{
  "_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:

```bash theme={null}
curl -X DELETE https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001 \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`204 No Content`): Empty body.

To delete multiple lists at once, send a `DELETE` to the lists collection endpoint:

```bash theme={null}
curl -X DELETE https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -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).

```bash theme={null}
curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/66f1a6e4698f1bca60425001/duplicate \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers (Copy)"
  }'
```

**Response** (`201 Created`):

```json theme={null}
{
  "_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).

```bash theme={null}
curl -X POST https://api-us-west-2-c1.benchmarkemail.com/api/contact-structure/64a1b2c3d4e5f6a7b8c9d0e1/lists/merge \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Subscribers (Merged)",
    "listIds": [
      "66f1a6e4698f1bca60425001",
      "66f1a6e4698f1bca60425002"
    ]
  }'
```

**Response** (`200 OK`):

```json theme={null}
{
  "_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](../rate-limits.md) |

## Next Steps

* [Manage Contacts](./manage-contacts.md) — create contacts and assign them to lists
* [Search Contacts](./search-contacts.md) — find contacts within a specific list
* [Manage Custom Fields](./manage-custom-fields.md) — define the fields on your contact structure
* [Migration from Legacy](./migration-from-legacy.md) — end-to-end data migration workflow