List Marketing Lists

Retrieve all marketing lists in the workspace with optional filtering.

Method

GET /v1/comms/lists

Query Parameters

source · string

Filter by list source (manual, import, signup_form, api).

limit · number

Maximum number of results (1-100, default 50).

offset · number

Number of results to skip for pagination (default 0).

Headers

Authorization · string · required

Bearer token (requires comms:read).

Request Example

cURL

curl "https://api.voyantcloud.com/v1/comms/lists?limit=10" \
  -H "Authorization: Bearer $VOYANT_API_KEY"

Response Fields

Each list item includes:

• id – List ID.
• workspace_id – Workspace owning the list.
• name – Human-readable name.
• description – Optional description.
• source – How the list was created.
• double_opt_in – Whether double opt-in is enabled.
• member_count – Number of subscribed members.
• created_at / updated_at – ISO timestamps.

Response Example

200 OK

{
  "items": [
    {
      "id": "lists_01J0CBFPXW7SP2N8A9Q7T2048Q",
      "workspace_id": "workspaces_01HZYPM2QF2R8X9SZQ0J9SYBCN",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter list",
      "source": "signup_form",
      "double_opt_in": true,
      "member_count": 1523,
      "created_at": "2025-01-08T10:22:31.000Z",
      "updated_at": "2025-02-02T14:12:40.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}