List Subscribers

List subscribers in your Lumail account with optional filters

GET https://lumail.io/api/v1/subscribers

List subscribers in your organization with optional filtering by tag, status, or search query. Results are sorted by creation date (most recent first).

Query Parameters

Parameter	Type	Default	Description
`tag`	string	—	Filter by tag name (case-insensitive). Only returns subscribers who have this tag.
`status`	string	`"SUBSCRIBED"`	Filter by subscriber status. One of: `SUBSCRIBED`, `UNSUBSCRIBED`, `PENDING_CONFIRMATION`, `BOUNCED`, `BANNED`, `COMPLAINED`.
`limit`	number	`50`	Maximum number of subscribers to return (1–100).
`query`	string	—	Search by name or email (case-insensitive partial match).

Response

Success (200 OK) — Returns a list of subscribers matching the filters.
Error (401 Unauthorized) — Invalid or missing API token.
Error (429 Too Many Requests) — Rate limit exceeded.

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`subscribers`	array	Array of subscriber objects
`subscribers[].id`	string	Unique identifier for the subscriber
`subscribers[].email`	string	Email address of the subscriber
`subscribers[].name`	string or null	Name of the subscriber (if provided)
`subscribers[].status`	string	Current status of the subscriber
`subscribers[].createdAt`	string	ISO 8601 timestamp of when the subscriber was added
`subscribers[].tags`	array	Array of tag objects associated with the subscriber

PreviousSend Email in Tiptap NextGet Tag by ID or Name

import { Lumail } from "lumail"; const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" }); // List all subscribers const { subscribers, total } = await lumail.subscribers.list(); // Filter by tag, status, and search const result = await lumail.subscribers.list({ tag: "newsletter", status: "SUBSCRIBED", limit: 10, query: "john", }); console.log(result.subscribers);

{ "success": true, "subscribers": [ { "id": "sub_TTYPR5tWDh", "email": "[email protected]", "name": "John Doe", "status": "SUBSCRIBED", "createdAt": "2026-04-02T10:30:00.000Z", "tags": [ { "id": "tag_JqaddtEx7z", "name": "newsletter" } ] }, { "id": "sub_Abc123xyz", "email": "[email protected]", "name": null, "status": "SUBSCRIBED", "createdAt": "2026-04-01T08:15:00.000Z", "tags": [ { "id": "tag_JqaddtEx7z", "name": "newsletter" }, { "id": "tag_rdEPhyjnfA", "name": "vip" } ] } ], "total": 142, "limit": 10 }

List Subscribers

Query Parameters

Response

Response Fields

Usage Examples