API reference

Contact lists

Named, hand-picked groups of contacts, for example beta testers. Target them from a broadcast with audience_filter: { lists: [id] }.

Being on a list is not consent: broadcasts still skip unsubscribed contacts and topic opt-outs.

The ContactList object

type ContactList = {
  id: string;                  // lst_…
  name: string; description: string | null;
  contact_count: number;       // all members
  active_count: number;        // members with status "active"
  created_at: string; updated_at: string;
};

List contact lists

GET/v1/lists

All lists, by name.

scope logs:read

curl https://api.mailpark.io/v1/lists \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "lst_beta",
      "name": "Beta testers",
      "description": "People who asked to try features early.",
      "contact_count": 42,
      "active_count": 40,
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-22T10:02:11Z"
    }
  ],
  "next_cursor": null
}

▶ Try it in the playground

Create a list

POST/v1/lists

A new, empty list. Names are unique per account.

scope contacts:write

Body

namestringrequired
Shown in the web app.
descriptionstring
What the list is for.

Errors

409list_exists

curl -X POST https://api.mailpark.io/v1/lists \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta testers",
    "description": "People who asked to try features early."
  }'

Response · 200

{
  "id": "lst_beta",
  "name": "Beta testers",
  "description": "People who asked to try features early.",
  "contact_count": 0,
  "active_count": 0,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

Get a list

GET/v1/lists/{id}

One list with its member counts.

Path parameters

idstringrequired
lst_…

curl https://api.mailpark.io/v1/lists/lst_beta \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "id": "lst_beta",
  "name": "Beta testers",
  "description": "People who asked to try features early.",
  "contact_count": 42,
  "active_count": 40,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

Rename a list

PATCH/v1/lists/{id}

Changes the name or description.

scope contacts:write

Path parameters

idstringrequired
lst_…

Body

namestring
New name.
descriptionstring
New description.

curl -X PATCH https://api.mailpark.io/v1/lists/lst_beta \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Early access"
  }'

Response · 200

{
  "id": "lst_beta",
  "name": "Early access",
  "description": "People who asked to try features early.",
  "contact_count": 42,
  "active_count": 40,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-22T10:02:11Z"
}

▶ Try it in the playground

Delete a list

DELETE/v1/lists/{id}

Deletes the list. Its contacts stay. Refused while an unfinished broadcast targets it.

scope contacts:write

Path parameters

idstringrequired
lst_…

Errors

409list_in_use

curl -X DELETE https://api.mailpark.io/v1/lists/lst_beta \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "deleted": true,
  "id": "lst_beta",
  "members_removed": 42
}

▶ Try it in the playground

List members

GET/v1/lists/{id}/contacts

The contacts on a list.

scope logs:read

Path parameters

idstringrequired
lst_…

Query parameters

statusstring
active, unsubscribed, bounced or complained.
limitinteger
How many to return, 1–100. Default 50.
cursorstring
The next_cursor from the previous page.

curl https://api.mailpark.io/v1/lists/lst_beta/contacts \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "con_7Yt1",
      "email": "jane@example.com",
      "external_id": "user_123",
      "fields": {
        "first_name": "Jane",
        "plan": "trial"
      },
      "topics": {
        "product-updates": true,
        "onboarding": true
      },
      "lists": [
        "lst_beta"
      ],
      "status": "active",
      "flags": [],
      "ev": {
        "signed_up": {
          "first": "2026-10-20T09:00:00Z",
          "last": "2026-10-20T09:00:00Z",
          "count": 1
        }
      },
      "created_at": "2026-10-20T09:00:00Z",
      "updated_at": "2026-10-22T10:02:11Z"
    }
  ],
  "next_cursor": null
}

▶ Try it in the playground

Add members

POST/v1/lists/{id}/contacts

Adds contacts by email or id, up to 1,000 of each per request. Unknown emails become new contacts.

scope contacts:write

Path parameters

idstringrequired
lst_…

Body

emailsstring[]
Email addresses.
contact_idsstring[]
Contact ids.

curl -X POST https://api.mailpark.io/v1/lists/lst_beta/contacts \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "jane@example.com",
      "sam@example.com"
    ]
  }'

Response · 200

{
  "id": "lst_beta",
  "name": "Beta testers",
  "description": "People who asked to try features early.",
  "contact_count": 44,
  "active_count": 42,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-22T10:02:11Z",
  "added": 2,
  "already_members": 0,
  "created": 1,
  "not_found": []
}

▶ Try it in the playground

Remove members

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

Takes contacts off the list. The contacts themselves stay.

scope contacts:write

Path parameters

idstringrequired
lst_…

Body

emailsstring[]
Email addresses.
contact_idsstring[]
Contact ids.

curl -X POST https://api.mailpark.io/v1/lists/lst_beta/contacts/remove \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "sam@example.com"
    ]
  }'

Response · 200

{
  "id": "lst_beta",
  "name": "Beta testers",
  "description": "People who asked to try features early.",
  "contact_count": 41,
  "active_count": 39,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-22T10:02:11Z",
  "removed": 1,
  "not_found": []
}

▶ Try it in the playground