Lumail
Product
Agents
PricingDocsChangelog
Log inSign up
IntroductionTutorialsAI IntegrationSDKAPI ReferenceIntegrationsFeaturesDeliverabilityWorkflows

Privacy & GDPR

GDPR in LumailData Processing Agreement (DPA) Status

Ship with Email

Choose an Email MCP for Claude Code, Then Ship the LaunchSend a Newsletter from Cursor, Then Ship the LaunchMove a Launch List from Kit Without Paying for Dormant Subscribers

Tutorials

Create an API TokenSend Transactional Email with SMTPSend React Email Templates with LumailBuild a V0 Capture PageDynamic Promo Codes with Webhooks

AI Integration

Claude Code (Plugin)Codex (Plugin)ChatGPT PluginHermesSkills (CLI)OpenClawCursor (MCP)TypeScript SDK IntegrationsTools API (v2)Examples & Recipes

SDK

SDK IntroductionSDK ConfigurationSDK ResourcesSDK ToolsErrors and Retries

API Reference

API TokensTypeScript SDKCLIMCP ServerTools API (v2)Admin Tools APIRate LimitsSMTP EndpointPOSTSend Transactional EmailPOSTSend Email in HTMLPOSTSend Email in MarkdownPOSTSend Email in TiptapPOSTEmail Verification APIPOSTCreate SubscriberGETGet SubscriberPATCHUpdate SubscriberPOSTUnsubscribe SubscriberPOSTAdd Tags to SubscriberDELETERemove Tags from SubscriberPOSTTrack EventGETGet Subscriber EventsGETGet All TagsPOSTCreate a TagGETList All CampaignsPOSTCreate CampaignGETGet CampaignPATCHUpdate CampaignDELETEDelete CampaignPOSTSend CampaignGETList SubscribersGETGet Tag by ID or Name

Integrations

ClickFunnels IntegrationSystemIO Integration

Features

Affiliate ProgramAccount VerificationLanguageVariablesTag Action LinksSurveysContent Deliverability CheckerSender HealthCampaign Delivery ScoreEmail Engagement ScoreSubscriber EventsRevenue TrackingEmail Sending Queue

Deliverability

How to strengthen DMARCHow to add DMARCHow to fix DKIMHow to verify a sending domainHow to fix MAIL FROMHow to fix BIMIHow to lower bounce rateHow to lower complaint rateHow to fix delivery delaysHow to fix blocklist bouncesHow to fix sending infrastructureHow to fix a dedicated IPHow to fix a failed sendHow to fix a fallback-domain sendHow to fix an invalid email parameterHow to fix sending rate or daily quotaHow to fix a monthly email limitHow to fix a past-due payment pauseHow to fix an admin sending pauseHow to complete additional verificationHow to fix a failed campaignHow to fix a campaign render error

Workflows

WorkflowWorkflow Getting StartedWorkflow TriggersWorkflow Manual EnrollmentWorkflow BranchingWorkflow A/B TestingWorkflow GoalsWorkflow Exit RulesWorkflow Publishing and VersionsWorkflow Test Runs and ResultsWait StepEmail StepAction StepWebhook StepWorkflow Groups

domains

Email DomainsWeb Domains

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

ParameterTypeDefaultDescription
tagstring—Filter by tag name (case-insensitive). Only returns subscribers who have this tag.
statusstring"SUBSCRIBED"Filter by subscriber status. One of: SUBSCRIBED, UNSUBSCRIBED, PENDING_CONFIRMATION, BOUNCED, BANNED, COMPLAINED, TRANSACTIONAL.
limitnumber50Maximum number of subscribers to return (1–100).
querystring—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

FieldTypeDescription
successbooleanIndicates if the operation was successful
subscribersarrayArray of subscriber objects
subscribers[].idstringUnique identifier for the subscriber
subscribers[].emailstringEmail address of the subscriber
subscribers[].namestring or nullName of the subscriber (if provided)
subscribers[].statusstringCurrent status of the subscriber
subscribers[].createdAtstringISO 8601 timestamp of when the subscriber was added
subscribers[].tags
PreviousSend CampaignNextGet Tag by ID or Name
MethodGET
Endpoint/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
}
array
Array of tag objects associated with the subscriber
subscribers[].tags[].idstringUnique identifier for the tag
subscribers[].tags[].namestringName of the tag
totalnumberTotal number of subscribers matching the filters
limitnumberThe 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

On This Page

Query ParametersResponseResponse FieldsUsage Examples