List subscribers
Lists subscribers with stable pagination and optional filtering by status, free-text query, tags, list, segment, attribute, or email. Non-attribute results are ordered by createdAt descending with subscriber ID as a deterministic tie-breaker. Attribute-filtered results use ClickHouse-first cursor pagination ordered by subscriber ID ascending and do not include a total count.
Query parameters
Page number
Number of items per page (max 100)
Opaque cursor returned as pagination.nextCursor. Only used with attribute filters.
Filter by subscriber status. Use all to disable status filtering.
Free-text search across email, first name, last name, and tags
Legacy alias for a partial email search
Comma-separated tag names. Subscribers must have all provided tags.
Custom attribute filter using attributeName:value syntax, such as plan:pro or mrr:50.
Attribute filter operator for direct cursor pagination. Use saved segments for exclusion operators such as is_not, not_contains, or is_empty.
Subscriber list ID or exact list name. The API tries ID first, then exact name.
Filter by subscriber list ID.
Filter by exact subscriber list name when the list ID is not known.
Filter by an existing segment ID
Response
Successful response
Example response
{
"success": true,
"subscribers": [
{
"id": "sub_abc123",
"email": "user@example.com",
"externalId": "user_123",
"firstName": "John",
"lastName": "Doe",
"phone": "+15551234567",
"smsStatus": "subscribed",
"status": "active",
"emailProvider": "gmail",
"tags": [
"premium",
"newsletter"
],
"customAttributes": {
"plan": "pro",
"signupSource": "website"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 100,
"totalPages": 5
}
}