Lists

A list is a group of contacts you can target with a campaign. Each campaign points to exactly one list, and a list can contain any number of active contacts. Lists are independent of each other: a contact can belong to multiple lists at the same time, and removing them from one list does not affect them in others or delete them from the system.

Schema

Field	Type	Description
`id`	string	Slug identifier for the list.
`name`	string	Descriptive name.
`key_id`	string	API key the list belongs to.
`contact_count`	integer	Number of contacts in the list.
`created_at`	string	Creation date (ISO 8601).

Operations

List all lists

GET /v1/bulk/lists

Returns an array with all lists in your account, including the contact_count for each one.

Create a list

POST /v1/bulk/lists

Body:

{ "name": "Newsletter Q3 2026" }

Returns 201 with the created list, including its automatically generated id.

Get a list with its contacts

GET /v1/bulk/lists/{id}

Returns the list details along with its paginated contacts.

Query parameters:

Parameter	Description
`limit`	Maximum number of contacts to return.
`offset`	Offset for pagination.
`status`	Filter contacts by status.

Rename a list

PATCH /v1/bulk/lists/{id}

Body:

{ "name": "Newsletter Q4 2026" }

Delete a list

DELETE /v1/bulk/lists/{id}

Deletes the list. Returns 204 No Content. If the list is referenced by an active campaign, returns 409 Conflict.

Add contacts to a list

POST /v1/bulk/lists/{id}/contacts

Body:

{ "emails": ["ana@empresa.com", "pedro@cliente.io"] }

The emails must correspond to contacts that already exist in your account. Returns 200 with the number of contacts added.

Remove a contact from a list

DELETE /v1/bulk/lists/{id}/contacts/{email}

Removes the contact from this list. Returns 204 No Content. The contact continues to exist in the system and in any other list it belongs to.

Clone a list

POST /v1/bulk/lists/{id}/duplicate

Creates a copy of the list with all its contacts. Useful for creating derived segments without starting from scratch. Returns 201 with the new list.

Bulk delete lists

POST /v1/bulk/lists/delete

Atomic deletion of multiple lists. Body:

{ "ids": ["newsletter-q3-abc123", "promo-verano-xyz"] }

Response:

{
  "requested": 2,
  "deleted": 1,
  "not_found": [],
  "forbidden": [],
  "in_use": ["promo-verano-xyz"]
}

Lists referenced by a campaign are reported in in_use and are not deleted. The remaining ones are deleted, even within the same request.

Examples

Create a list and add contacts

# 1. Create the list
curl -X POST https://api.mailerdash.com/v1/bulk/lists \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Q3 2026"}'

# 2. Add contacts (use emails already registered as contacts)
curl -X POST https://api.mailerdash.com/v1/bulk/lists/newsletter-q3-2026-abc123/contacts \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["ana@empresa.com", "pedro@cliente.io"]}'

Reference

For the full request/response schema and error codes, see the bulk API reference.