Lumail — 电子邮件营销命令行工具（CLI）与软件开发套件（SDK）

可通过命令行工具（pnpm lumail）或 TypeScript SDK（import { Lumail } from "@/lib/lumail-sdk"）与 Lumail API 进行交互。

快速开始

# 首先设置您的 API 密钥
pnpm lumail auth set 

# 验证是否配置成功
pnpm lumail auth test

CLI 参考文档

所有 CLI 命令均通过 pnpm lumail 执行。每个命令均支持全局标志（Global Flags）。

全局标志

身份验证

pnpm lumail auth set        # 保存 API 密钥（路径：~/.config/lumail/token）
pnpm lumail auth show              # 显示脱敏后的密钥
pnpm lumail auth show --raw        # 显示完整密钥
pnpm lumail auth remove            # 删除已保存的密钥
pnpm lumail auth test              # 验证密钥有效性

订阅者（Subscribers）

# 创建或更新（upsert）订阅者
pnpm lumail subscribers create --email user@example.com --name "John" --tags vip beta

# 通过邮箱或 ID 获取订阅者
pnpm lumail subscribers get user@example.com

# 更新订阅者
pnpm lumail subscribers update user@example.com --name "John Doe"
pnpm lumail subscribers update user@example.com --tags premium --replace-tags

# 删除订阅者
pnpm lumail subscribers delete user@example.com

# 退订（Unsubscribe）
pnpm lumail subscribers unsubscribe user@example.com

# 管理标签（Tags）
pnpm lumail subscribers add-tags user@example.com --tags vip premium
pnpm lumail subscribers remove-tags user@example.com --tags old-tag

# 列出事件（Events）
pnpm lumail subscribers events user@example.com --take 50 --order desc

营销活动（Campaigns）

# 列出营销活动
pnpm lumail campaigns list
pnpm lumail campaigns list --status DRAFT --page 1 --limit 50
pnpm lumail campaigns list --query "welcome" --json

# 创建营销活动
pnpm lumail campaigns create --subject "Welcome!" --name "Welcome Campaign"

# 获取营销活动详情
pnpm lumail campaigns get 

# 更新营销活动（仅限 DRAFT 状态）
pnpm lumail campaigns update  --subject "Updated Subject" --preview "Preview text"

# 删除营销活动（仅限 DRAFT 状态）
pnpm lumail campaigns delete 

# 立即发送
pnpm lumail campaigns send 

# 定时发送
pnpm lumail campaigns send  --scheduled-at 2025-12-25T10:00:00Z --timezone UTC

标签（Tags）

pnpm lumail tags list
pnpm lumail tags create --name "premium"
pnpm lumail tags get premium          # 支持按名称或 ID 查询
pnpm lumail tags update  --name "gold"

邮件（Transactional Emails）

# 发送事务性邮件
pnpm lumail emails send 
  --to user@example.com 
  --from noreply@yourdomain.com 
  --subject "Order Confirmation" 
  --content "Your order #123 is confirmed." 
  --content-type MARKDOWN

# 禁用追踪功能
pnpm lumail emails send --to x --from y --subject z --content "Hello" --transactional

# 验证邮箱地址
pnpm lumail emails verify user@example.com

事件（Events）

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

支持的事件类型：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）

V2 工具 API 提供了 59+ 个面向 AI Agent 和高级操作的工具。

# 列出所有可用工具
pnpm lumail tools list

# 获取工具 Schema
pnpm lumail tools get list_subscribers

# 执行工具
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 参考文档

SDK 源码位于 src/lib/lumail-sdk/，可通过 @/lib/lumail-sdk 导入使用。

初始化配置

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

const lumail = new Lumail({
  apiKey: "lm_...",
  baseUrl: "https://lumail.io/api", // 可选，默认为此值
});

订阅者（Subscribers）

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

// 通过邮箱或 ID 获取
const { subscriber } = await lumail.subscribers.get("user@example.com");

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

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

// 退订（Unsubscribe）
await lumail.subscribers.unsubscribe("user@example.com");

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

// 事件列表（基于游标分页）
const { events, nextCursor } = await lumail.subscribers.listEvents("user@example.com", {
  take: 20,
  order: "desc",
  eventTypes: ["EMAIL_OPENED", "EMAIL_CLICKED"],
});

营销活动（Campaigns）

// 分页列出
const { campaigns, total, pageCount } = await lumail.campaigns.list({
  status: "DRAFT",
  page: 1,
  limit: 20,
  query: "welcome",
});

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

// 获取详情
const { campaign } = await lumail.campaigns.get(campaignId);

// 更新（仅限 DRAFT 状态）
await lumail.campaigns.update(campaignId, { subject: "Updated Subject" });

// 删除（仅限 DRAFT 状态）
await lumail.campaigns.delete(campaignId);

// 立即发送
await lumail.campaigns.send(campaignId);

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

邮件（Transactional Emails）

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

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

标签（Tags）

const { tags } = await lumail.tags.list();
const { tag } = await lumail.tags.create({ name: "premium" });
const { tag } = await lumail.tags.get("premium"); // 支持按名称或 ID 查询
await lumail.tags.update("premium", { name: "gold" });

事件（Events）

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

工具（Tools，V2 API）

// 列出所有工具
const { tools, grouped } = await lumail.tools.list();

// 获取工具 Schema
const { tool } = await lumail.tools.get("list_subscribers");

// 执行工具并指定响应类型
const result = await lumail.tools.run<{ subscribers: unknown[] }>(
  "list_subscribers",
  { limit: 10 },
);

错误处理

SDK 抛出强类型的错误对象，可捕获特定错误类型：

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 - 订阅者未找到
  } else if (error instanceof LumailAuthenticationError) {
    // 401 - API 密钥无效
  } else if (error instanceof LumailRateLimitError) {
    // 429 - 请求频率超限，error.retryAfter 提供毫秒级重试延迟
  } else if (error instanceof LumailPaymentRequiredError) {
    // 402 - 达到套餐用量上限
  } else if (error instanceof LumailValidationError) {
    // 400 - 请求参数校验失败
  }
}

重试策略

• GET / PUT / DELETE 请求在遇到网络错误或 429 响应时最多重试 3 次
• POST / PATCH 请求不自动重试（防止重复创建订阅者或邮件）
• 重试延迟：1 秒、2 秒、4 秒（指数退避）
• 尊重服务端返回的 Retry-After 响应头
• 单次请求默认超时时间为 30 秒

npm 包

发布于 npm，包名为 lumail，同时提供 CLI 和库两种使用方式：

# CLI 使用方式（需先执行：npm install -g lumail）
npx lumail auth set 
npx lumail subscribers create --email user@example.com

# 库使用方式
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "lm_..." });

包源码路径：packages/lumail/
构建命令：bun run build（在 packages/lumail/ 目录下执行）
自动发布：向 main 分支推送代码将触发 GitHub Actions 自动发布流程

文件路径说明