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.

Public sign-up form

Every list can have a public form where people subscribe themselves. It’s what you point an ad at, or what you embed on your site.

Check the status

GET /v1/bulk/lists/{id}/signup-form

Enable or reconfigure

PUT /v1/bulk/lists/{id}/signup-form

Optional body:

Field	Type	Description
tags	array	Tags applied to everyone who comes in through this form. Useful for knowing which ad each person came from.
redirect_url	string	Where to send them after subscribing. Empty = our thank-you page.
regenerate	boolean	Rotates the form’s token.

The response carries:

Field	Description
activo	Whether the form is accepting sign-ups.
url	Page hosted by us, ready to use.
snippet	Ready-to-paste HTML for your own site.
token	The form’s public identifier.
doble_optin	Whether this list requires confirmation.

Turn it off

DELETE /v1/bulk/lists/{id}/signup-form

`regenerate` revokes what you already published

regenerate: true changes the token, so a form already embedded on a site stops working and you’ll need to publish the new one. Use it when the token leaked or someone is abusing it, not as routine.

An open form is not the same as an import

Anyone can type someone else’s address into a public form. If yours sits on an open page, the double opt-in below is what proves the owner of that address actually wanted to subscribe.

A sign-up through this form does fire sequences with list_join, unlike a bulk import. See the Ad leads — from the dashboard guide.

Double opt-in (subscription confirmation)

You can require contacts to confirm their subscription before receiving campaigns from a list — it protects your sending reputation and is the standard (Mailchimp-style) way to record explicit consent.

Configure double opt-in

PUT /v1/bulk/lists/{id}/confirmation

Body:

{
  "require_confirmation": true,
  "confirm_from_email": "noreply@tuempresa.com",
  "confirm_from_name": "Your Company",
  "confirm_subject": "Confirm your subscription",
  "confirm_intro": "Thanks for subscribing. Confirm your email to start receiving our emails."
}

confirm_from_email must belong to a verified domain on your account (same rule as a campaign’s from). Turning on require_confirmation for a list that already has members automatically marks those existing members as confirmed (they aren’t asked to confirm retroactively) — only contacts you add after that go through the confirmation flow.

While a list requires confirmation, every new contact added via POST /v1/bulk/lists/{id}/contacts automatically receives an email with a one-click confirmation link (public endpoint GET /confirm-subscription?token=...). A contact who hasn’t confirmed stays in a pending state and is excluded from campaign sends to that list until they confirm.

---

Resend confirmation to a pending contact

POST /v1/bulk/lists/{id}/contacts/{email}/resend-confirmation

Resends the confirmation email. Returns 400 if the list doesn’t require confirmation, and 429 if you already resent it less than 5 minutes ago (anti mail-bomb protection).

{ "resent": true }

Tip

The contact.confirmed webhook event fires when a contact confirms their subscription — use it to sync state into your own systems. See webhooks.

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"]}'

Tip

Removing a contact from a list does not delete them from the system or remove them from other lists. To permanently delete them from your account, use DELETE /v1/bulk/contacts/{email}.

Caution

You cannot delete a list that is in use by an active campaign. Cancel or wait for the campaign to finish before deleting the list. If you use bulk delete, lists that are in_use are reported without being deleted — the rest are deleted.

Reference

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