Lists

Manage static and dynamic lists, and control list membership.

GET

/lists

List all lists with member counts.

Query Parameters

Name	Type	Required	Description
type	string	Optional	Filter by list type: "static" or "dynamic".
limit	integer	Optional	Number of lists to return (default: 100, max: 1000).
offset	integer	Optional	Number of lists to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/lists?type=static&limit=20" \
  -H "Authorization: Bearer tm_live_abc123"

POST

/lists

Create a new list.

Request Body

Name	Type	Required	Description
name	string	Required	List name (max 100 characters).
description	string	Optional	List description (max 500 characters).
type	string	Optional	"static" (default) or "dynamic". Dynamic lists require conditions.
conditions	object	Optional	Segment conditions for dynamic lists. Required when type is "dynamic".

curl -X POST https://api.topmail.so/api/v1/lists \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customers",
    "description": "High-value customers",
    "type": "static"
  }'

GET

/lists/:id

Retrieve a single list by ID with member count.

curl https://api.topmail.so/api/v1/lists/LIST_ID \
  -H "Authorization: Bearer tm_live_abc123"

PATCH

/lists/:id

Update a list. Only provided fields are modified.

Request Body

Name	Type	Required	Description
name	string	Optional	Updated list name (max 100 characters).
description	string \| null	Optional	Updated description. Set to null to clear.
conditions	object	Optional	Updated segment conditions (only for dynamic lists).

curl -X PATCH https://api.topmail.so/api/v1/lists/LIST_ID \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Customers"}'

DELETE

/lists/:id

Permanently delete a list. Members are not deleted.

curl -X DELETE https://api.topmail.so/api/v1/lists/LIST_ID \
  -H "Authorization: Bearer tm_live_abc123"

List Members

Manage contacts within a static list.

GET

/lists/:id/members

List members of a list with contact details.

Query Parameters

Name	Type	Required	Description
limit	integer	Optional	Number of members to return (default: 100, max: 1000).
offset	integer	Optional	Number of members to skip for pagination (default: 0).

curl "https://api.topmail.so/api/v1/lists/LIST_ID/members?limit=50" \
  -H "Authorization: Bearer tm_live_abc123"

POST

/lists/:id/members

Add contacts to a static list. Cannot be used on dynamic lists.

Request Body

Name	Type	Required	Description
contact_ids	string[]	Required	Array of contact UUIDs to add (min: 1, max: 500).

curl -X POST https://api.topmail.so/api/v1/lists/LIST_ID/members \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "c2b3c4d5-e6f7-8901-bcde-f12345678901"
    ]
  }'

The response may also include already_in_list (count of contacts already present) and invalid_ids (array of IDs that don't exist in your workspace).

DELETE

/lists/:id/members

Remove contacts from a static list. The contacts are not deleted.

Request Body

Name	Type	Required	Description
contact_ids	string[]	Required	Array of contact UUIDs to remove (min: 1, max: 500).

curl -X DELETE https://api.topmail.so/api/v1/lists/LIST_ID/members \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": ["c1a2b3c4-d5e6-7890-abcd-ef1234567890"]
  }'