Lists#

Lists are the audiences within a project, and the unit consent attaches to. A list slug is what recipientMode: "list:<slug>" refers to when you send.

GET /api/lists#

Every list in the project, with subscriber counts.

Scope: lists:read

Parameter	In	Type	Notes
projectId	query	string	Required.

curl "https://pharosbase.com/api/lists?projectId=acme-app" \
  -H "Authorization: Bearer $PHAROS_API_KEY"

{
  "lists": [
    {
      "id": "lst_…",
      "name": "Newsletter",
      "slug": "newsletter",
      "description": null,
      "isDefault": true,
      "subscriberCount": 4102,
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}

subscriberCount counts only subscribed rows — unsubscribed and pending members are not included.

POST /api/lists#

Create a list.

Scope: lists:write

Field	Type	Notes
projectId	string	Required.
name	string	Required.
slug	string	Derived from name when omitted. Unique within the project.
description	string
isDefault	boolean	Marking a list default un-defaults the previous one.

201:

{ "id": "lst_…", "slug": "product-updates" }

The default list is where POST /api/contacts subscribes new contacts when no list is named, so exactly one list is default at a time.

PATCH /api/lists/{id}#

Update a list's name, slug, description or isDefault. Only the fields you pass change.

Scope: lists:write

{ "success": true }

Passing no recognised field returns 400.

Changing a slug breaks any recipientMode: "list:<old-slug>" still stored on a draft campaign, and any integration that syncs by listSlug. Prefer renaming the display name.

DELETE /api/lists/{id}#

Delete a list and every subscription on it.

Scope: lists:write

{ "success": true }

The contacts survive; only their membership of this list is removed. Because consent lives on the subscription, deleting a list also deletes the record of who had opted out of it — if those people are still reachable through another list, that history is gone. Unsubscribe rather than delete when the list is still in use.