List Subscribers

List subscribers in your Lumail account with optional filters

MethodGET

/api/v1/subscribers

Request Examples

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);

Response Examples

{
  "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
}

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`, `TRANSACTIONAL`.
`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
`subscribers[].tags[].id`	string	Unique identifier for the tag
`subscribers[].tags[].name`	string	Name of the tag
`total`	number	Total number of subscribers matching the filters
`limit`	number	The limit used in the query

Usage Examples

Use this endpoint to:

Fetch subscribers by tag for integrations (e.g., display recent signups from a specific campaign)
Search for subscribers by name or email
List subscribers with a specific status for reporting
Power dashboards or external tools that need subscriber data

PreviousSend Email in Tiptap NextGet Tag by ID or Name