Lumail - Email Marketing CLI & SDK#

Interact with the Lumail API using either the CLI ( pnpm lumail) or the TypeScript SDK ( import { Lumail } from "@/lib/lumail-sdk").

Quick Start#

bash

# Set your API key first
pnpm lumail auth set <your-api-key>

# Verify it works
pnpm lumail auth test

CLI Reference#

All CLI commands run via pnpm lumail <command>. Every command supports global flags.

Global Flags#

FlagDescription--jsonOutput as JSON--format <text|json|csv>Output format (default: text)--verboseEnable debug logging--no-colorDisable colored output--no-headerOmit table headers (for piping)

Authentication#

bash

pnpm lumail auth set <token>       # Save API key (~/.config/lumail/token)
pnpm lumail auth show              # Show masked token
pnpm lumail auth show --raw        # Show full token
pnpm lumail auth remove            # Delete saved token
pnpm lumail auth test              # Verify token is valid

Subscribers#

bash

# Create or upsert a subscriber
pnpm lumail subscribers create --email user@example.com --name "John" --tags vip beta

# Get subscriber by email or ID
pnpm lumail subscribers get user@example.com

# Update subscriber
pnpm lumail subscribers update user@example.com --name "John Doe"
pnpm lumail subscribers update user@example.com --tags premium --replace-tags

# Delete subscriber
pnpm lumail subscribers delete user@example.com

# Unsubscribe
pnpm lumail subscribers unsubscribe user@example.com

# Manage tags
pnpm lumail subscribers add-tags user@example.com --tags vip premium
pnpm lumail subscribers remove-tags user@example.com --tags old-tag

# List events
pnpm lumail subscribers events user@example.com --take 50 --order desc

Campaigns#

bash

# List campaigns
pnpm lumail campaigns list
pnpm lumail campaigns list --status DRAFT --page 1 --limit 50
pnpm lumail campaigns list --query "welcome" --json

# Create campaign
pnpm lumail campaigns create --subject "Welcome!" --name "Welcome Campaign"

# Get campaign details
pnpm lumail campaigns get <campaignId>

# Update campaign (DRAFT only)
pnpm lumail campaigns update <campaignId> --subject "Updated Subject" --preview "Preview text"

# Delete campaign (DRAFT only)
pnpm lumail campaigns delete <campaignId>

# Send immediately
pnpm lumail campaigns send <campaignId>

# Schedule for later
pnpm lumail campaigns send <campaignId> --scheduled-at 2025-12-25T10:00:00Z --timezone UTC

Tags#

bash

pnpm lumail tags list
pnpm lumail tags create --name "premium"
pnpm lumail tags get premium          # By name or ID
pnpm lumail tags update <id> --name "gold"

Emails (Transactional)#

bash

# Send transactional email
pnpm lumail emails send \
  --to user@example.com \
  --from noreply@yourdomain.com \
  --subject "Order Confirmation" \
  --content "Your order #123 is confirmed." \
  --content-type MARKDOWN

# With tracking disabled
pnpm lumail emails send --to x --from y --subject z --content "Hello" --transactional

# Verify email address
pnpm lumail emails verify user@example.com

Events#

bash

pnpm lumail events create \
  --type SUBSCRIBER_PAYMENT \
  --subscriber user@example.com \
  --data '{"amount": 99, "plan": "pro"}'

Event types: SUBSCRIBED, UNSUBSCRIBED, TAG_ADDED, TAG_REMOVED, EMAIL_OPENED, EMAIL_CLICKED, EMAIL_SENT, EMAIL_RECEIVED, WORKFLOW_STARTED, WORKFLOW_COMPLETED, WORKFLOW_CANCELED, FIELD_UPDATED, EMAIL_BOUNCED, EMAIL_COMPLAINED, WEBHOOK_EXECUTED, SUBSCRIBER_PAYMENT, SUBSCRIBER_REFUND

Tools (V2 API)#

The V2 tools API provides 59+ tools for AI agents and advanced operations.

bash

# List all available tools
pnpm lumail tools list

# Get tool schema
pnpm lumail tools get list_subscribers

# Run a tool
pnpm lumail tools run list_subscribers --params '{"limit": 10, "status": "SUBSCRIBED"}'
pnpm lumail tools run create_campaign --params '{"name": "Test", "subject": "Hello"}'
pnpm lumail tools run send_campaign --params '{"campaignId": "abc123"}'

SDK Reference#

The SDK lives at src/lib/lumail-sdk/ and is importable via @/lib/lumail-sdk.

Setup#

typescript

import { Lumail } from "@/lib/lumail-sdk";

const lumail = new Lumail({
  apiKey: "lm_...",
  baseUrl: "https://lumail.io/api", // optional, defaults to this
});

Subscribers#

typescript

// Create/upsert
const { subscriber } = await lumail.subscribers.create({
  email: "user@example.com",
  name: "John",
  tags: ["vip", "beta"],
  fields: { company: "Acme" },
  triggerWorkflows: true,
});

// Get by email or ID
const { subscriber } = await lumail.subscribers.get("user@example.com");

// Update
await lumail.subscribers.update("user@example.com", { name: "John Doe" });

// Delete
await lumail.subscribers.delete("user@example.com");

// Unsubscribe
await lumail.subscribers.unsubscribe("user@example.com");

// Tags
await lumail.subscribers.addTags("user@example.com", ["premium"]);
await lumail.subscribers.removeTags("user@example.com", ["old-tag"]);

// Events (cursor-based pagination)
const { events, nextCursor } = await lumail.subscribers.listEvents("user@example.com", {
  take: 20,
  order: "desc",
  eventTypes: ["EMAIL_OPENED", "EMAIL_CLICKED"],
});

Campaigns#

typescript

// List with pagination
const { campaigns, total, pageCount } = await lumail.campaigns.list({
  status: "DRAFT",
  page: 1,
  limit: 20,
  query: "welcome",
});

// Create
const { campaign, campaignId } = await lumail.campaigns.create({
  subject: "Welcome!",
  name: "Welcome Campaign",
  contentType: "MARKDOWN",
});

// Get
const { campaign } = await lumail.campaigns.get(campaignId);

// Update (DRAFT only)
await lumail.campaigns.update(campaignId, { subject: "Updated Subject" });

// Delete (DRAFT only)
await lumail.campaigns.delete(campaignId);

// Send immediately
await lumail.campaigns.send(campaignId);

// Schedule
await lumail.campaigns.send(campaignId, {
  scheduledAt: "2025-12-25T10:00:00Z",
  timezone: "UTC",
});

Emails (Transactional)#

typescript

const { qstashMessageId } = await lumail.emails.send({
  to: "user@example.com",
  from: "noreply@yourdomain.com",
  subject: "Order Confirmation",
  content: "Your order is confirmed.",
  contentType: "MARKDOWN", // "MARKDOWN" | "HTML" | "TIPTAP"
  tracking: { links: true, open: true },
});

// Verify email
const { isValid } = await lumail.emails.verify({ email: "test@example.com" });

Tags#

typescript

const { tags } = await lumail.tags.list();
const { tag } = await lumail.tags.create({ name: "premium" });
const { tag } = await lumail.tags.get("premium"); // by name or ID
await lumail.tags.update("premium", { name: "gold" });

Events#

typescript

await lumail.events.create({
  eventType: "SUBSCRIBER_PAYMENT",
  subscriber: "user@example.com",
  data: { amount: 99, plan: "pro" },
});

Tools (V2 API)#

typescript

// List all tools
const { tools, grouped } = await lumail.tools.list();

// Get tool schema
const { tool } = await lumail.tools.get("list_subscribers");

// Run a tool with typed response
const result = await lumail.tools.run<{ subscribers: unknown[] }>(
  "list_subscribers",
  { limit: 10 },
);

Error Handling#

The SDK throws typed errors - catch specific error types:

typescript

import {
  Lumail,
  LumailAuthenticationError,
  LumailNotFoundError,
  LumailRateLimitError,
  LumailValidationError,
  LumailPaymentRequiredError,
} from "@/lib/lumail-sdk";

try {
  await lumail.subscribers.get("unknown@example.com");
} catch (error) {
  if (error instanceof LumailNotFoundError) {
    // 404 - subscriber not found
  } else if (error instanceof LumailAuthenticationError) {
    // 401 - invalid API key
  } else if (error instanceof LumailRateLimitError) {
    // 429 - rate limited, error.retryAfter has delay in ms
  } else if (error instanceof LumailPaymentRequiredError) {
    // 402 - plan limit reached
  } else if (error instanceof LumailValidationError) {
    // 400 - invalid request
  }
}

Retry Behavior#

• GET/PUT/DELETE requests retry up to 3 times on network errors and 429s
• POST/PATCH requests do NOT retry (prevents duplicate subscribers/emails)
• Retry delays: 1s, 2s, 4s (exponential backoff)
• Respects Retry-After header from rate limit responses
• Default timeout: 30s per request

npm Package#

Published as lumail on npm. Dual CLI + library:

bash

# CLI usage (after npm install -g lumail)
npx lumail auth set <token>
npx lumail subscribers create --email user@example.com

# Library usage
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "lm_..." });

Package source: packages/lumail/ Build: bun run build (in packages/lumail/) Auto-release: pushes to main trigger GitHub Actions release

File Locations#

ComponentPathSDK sourcesrc/lib/lumail-sdk/CLI sourcesrc/cli/npm packagepackages/lumail/Build scriptpackages/lumail/build.tsTests__tests__/lumail-sdk.test.ts, __tests__/lumail-cli.test.tsAPI docscontent/docs/api-reference/GH Action.github/workflows/release-lumail.yml