list_subscribers
Paginated list of project members with optional filters by project, status, and free-text search.
List members (project subscribers) with optional filters by project_id, status, and a free-text search across name, email and billing email. Results are scoped to the token's team and ordered newest-first.
Emails are returned verbatim. Scrub before forwarding to external systems.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_idstringoptionalOptional project UUID to narrow the result.
statusstringoptionalMember status filter. One of: lead, trialing, customer, churned, banned
leadtrialingcustomerchurnedbannedsearchstringoptionalCase-insensitive partial match against name + email.
limitintegeroptionalMaximum members to return per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "name": "Jane Doe", "email": "jane@example.com", "email_verified": true, "billing_email": "jane@example.com", "identities": [ { "connector": "telegram", "external_id": "123456789", "display_name": "Jane Doe", "username": "janedoe", "preferred": true } ], "status": "customer", "joined_at": "2026-05-18T10:05:00Z" } ], "meta": { "page": 1, "limit": 25, "total": 41, "has_more": true }}How it fails
TOKEN_MISSING_ABILITYtoken lacks project-user:view-any.
RESOURCE_NOT_FOUNDproject_id names a project the token cannot see: unknown, another team's, or outside the token's scope:project: allow-list. Without a project_id, the list spans only the projects the allow-list admits.
VALIDATION_FAILEDstatus is not one of the member statuses; the error context lists the supported values.
Caveats
emailandbilling_emailmean different things.emailis an address the member chose and verified, and is their portal sign-in credential.billing_emailis whatever they typed at a payment provider's checkout — never verified, never used for authentication. Do not treat abilling_emailas a confirmed way to reach someone.- Most members have
email: null. They join through a bot and are never asked for one, sobilling_emailis often the only address on record — which is what makes it useful for matching a refund request to a subscription. billing_emailisnullfor anyone who joined by redeeming an access code, because no payment ever took place. It is alsonullfor members whose last payment predates automatic capture.
How is this guide?
Last updated on