Resources

Email lists API

Create, list, update and delete email lists, including subscriber statistics and custom fields.

How lists work

A list is a container for subscribers - your newsletter audience, your customers, your webinar registrants. Campaigns are sent to a list (or to a segment built on a list), and signup forms and API-created subscribers always land on a specific list. Most accounts work fine with a handful of lists and use segments for finer targeting, so prefer segments over many small lists.

Lists also define the custom_fields available on their subscribers: declare field names such as company or phone on the list, then set values per subscriber through the Subscribers API.

Use cases

Create a list programmatically when onboarding a new brand, region or product line.
Fetch subscriber statistics per status to power your own dashboard.
Define custom fields once on the list, then fill them per subscriber during signup or sync.
Fetch the most recent subscribers on a list for a quick activity overview.

Endpoints

GET

Get email lists

/email-lists-api

Query parameters

Name	Type	Description
`status`	string	Filter by status (active, inactive).
`search`	string	Search by name or description.
`include_stats`	boolean	Include subscriber statistics.
`limit`	number	Items per page (default: 50).
`offset`	number	Pagination offset.

curl -X GET "https://api.mailingplatform.net/email-lists-api?include_stats=true&limit=50" \
  -H "Authorization: Bearer mp_live_..."

POST

Create email list

/email-lists-api

Request body

Name	Type	Description
`name`required	string	List name.
`description`	string	List description.
`status`	string	List status, for example active.
`custom_fields`	object[]	Field definitions ({ name, type, options, show_in_preferences }). show_in_preferences controls the preference center and defaults to false.

curl -X POST "https://api.mailingplatform.net/email-lists-api" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter Subscribers",
  "description": "Main newsletter mailing list",
  "status": "active",
  "custom_fields": ["company", "phone", "industry"]
}'

GET

Get single list

/email-lists-api/{listId}

Retrieve one list by id. The response always includes subscriber_stats with counts per status.

Query parameters

Name	Type	Description
`listId`required	string	List id (path).
`include_subscribers`	boolean	When true, includes the 100 most recent subscribers on the list.

curl -X GET "https://api.mailingplatform.net/email-lists-api/{listId}?include_subscribers=true" \
  -H "Authorization: Bearer mp_live_..."

PUT

Update list

/email-lists-api/{listId}

Update a list. All fields are optional; only the fields you send are changed.

Request body (partial)

Name	Type	Description
`name`	string	List name.
`description`	string	List description.
`status`	string	List status, for example active.
`custom_fields`	object[]	Field definitions ({ name, type, options, show_in_preferences }). show_in_preferences controls the preference center and defaults to false.

curl -X PUT "https://api.mailingplatform.net/email-lists-api/{listId}" \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP customers", "status": "active"}'

DELETE

Delete list

/email-lists-api/{listId}

Delete an empty list. Lists that still have subscribers cannot be deleted; remove the subscribers first.

Name	Type	Description
`listId`required	string	List id (path).

curl -X DELETE "https://api.mailingplatform.net/email-lists-api/{listId}" \
  -H "Authorization: Bearer mp_live_..."