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.
sendable_count	integer	How many can be sent to: active and, if the list requires confirmation, already confirmed.
pending_count	integer	Active but pending confirmation (double opt-in lists only).
health	integer | null	List health, 0-100. null if the list is empty.
deliverable_pct	integer | null	% of the list that can receive: active and not suppressed.
suppressed_pct	integer | null	% of the list with a live suppression on your account.
engaged_pct	integer | null	% that opened, out of those who received in the last 90 days. null if nobody received anything in the window.
sent_window	integer	How many contacts of the list received something in the last 90 days.
created_at	string	Creation date (ISO 8601).

List health

Every list carries a 0-100 score that combines deliverability (60%) and engagement (40%). Deliverability weighs more because it is the one that costs you reputation: sending to addresses that don’t exist or that already complained is what makes your mail start landing in spam.

Suppressed is not the same as unsubscribed. sendable_count looks at the contact’s status; suppressed_pct looks at your account’s suppressions, which include hard bounces, complaints and whatever you imported from another provider. That’s why a list can say “1,000 sendable” and have 200 that will never receive — that gap is what the score makes visible.

Two things the score deliberately does not do:

• If nobody received anything in the last 90 days, engaged_pct is null, not 0. A list that isn’t used isn’t sick: there’s no data. The score is then computed from deliverability alone and the panel shows “no sends”. What you want to catch is the stale list that is still being used.
• An empty list does not score 100. It scores nothing (null): there is nothing to measure.

Engagement is measured with human opens. Apple Mail Privacy Protection preloads and corporate scanners fetch the pixel as soon as the mail arrives, with nobody reading it, and counting those would inflate the number precisely on the worst lists.

What to do with the number

Signal	What it means	What to do
High suppressed_pct	A good share of the list can no longer receive	Clean the list: those contacts only dilute your metrics
Low engaged_pct with recent sends	They still receive you but don’t read you	Re-engagement campaign, and lower the frequency — see campaigns
engaged_pct is null	The list hasn’t been used in 90 days	If you’re reactivating it, start with a re-confirmation instead of blasting it

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.