名称： cold-email
描述： 使用 AI 生成高度个性化的冷启动邮件序列。将潜在客户数据转化为高转化率的推广活动。
元数据：
clawdbot:
requires:
env:
- MACHFIVE_API_KEY

MachFive - AI 冷启动邮件生成器

根据潜在客户数据生成个性化的冷启动邮件序列。MachFive 利用 AI 研究潜在客户并撰写独特、相关的推广内容，而非使用模板。

设置

1. 在 https://app.machfive.io/settings（集成 → API 密钥）获取您的 API 密钥。
2. 在您的环境中设置 MACHFIVE_API_KEY。

活动 ID

每个生成请求都需要在 URL 中指定一个活动 ID：/api/v1/campaigns/{campaign_id}/generate（或 /generate-batch）。

• 如果用户未提供活动名称或 ID： 调用 GET /api/v1/campaigns（见下文）列出其工作空间中的活动，然后在运行生成请求前，请用户通过名称或 ID 选择一个。
• 手动获取位置： https://app.machfive.io/campaigns → 打开一个活动 → 从 URL 或设置中复制 ID。
• 无默认值： 本技能不假定任何活动。用户（或代理配置）必须提供一个。如果用户提供了默认活动 ID（例如“为我的请求使用活动 X”），代理可以为其工作空间存储一个默认的活动 ID。

端点

列出活动（生成前发现）

列出工作空间中的活动，以便在用户未提供名称或 ID 时，代理可以询问用户使用哪个活动。

GET https://app.machfive.io/api/v1/campaigns
Authorization: Bearer {MACHFIVE_API_KEY}

或使用 X-API-Key: {MACHFIVE_API_KEY} 请求头。

可选查询参数：?q=search 或 ?name=search 用于按活动名称过滤。

响应 (200):

{
  "campaigns": [
    { "id": "cb1bbb14-e576-4d8f-a8f3-6fa929076fd8", "name": "SaaS Q1 推广", "created_at": "2025-01-15T12:00:00Z" },
    { "id": "a1b2c3d4-...", "name": "企业潜在客户", "created_at": "2025-01-10T08:00:00Z" }
  ]
}

如果未提供活动名称或 ID，请先调用此接口，然后询问用户：“我应该使用哪个活动？[列出名称/ID]。”

单个潜在客户（同步）

为一个潜在客户生成邮件序列（每个潜在客户 3–5 封邮件）。等待完成，直接返回序列。请求可能需要 3–5 分钟（AI 研究 + 生成）；请使用至少 300 秒（5 分钟） 或 600 秒（10 分钟） 的客户端超时设置。不要使用 120 秒超时，否则响应会被截断。

POST https://app.machfive.io/api/v1/campaigns/{campaign_id}/generate
Authorization: Bearer {MACHFIVE_API_KEY}
Content-Type: application/json

或使用 X-API-Key: {MACHFIVE_API_KEY} 请求头。

{
  "lead": {
    "name": "张三",
    "title": "市场副总裁",
    "company": "Acme 公司",
    "email": "john@acme.com",
    "company_website": "https://acme.com",
    "linkedin_url": "https://linkedin.com/in/johnsmith"
  },
  "options": {
    "list_name": "Q1 推广",
    "email_count": 3,
    "email_signature": "祝好，\n您的姓名",
    "approved_ctas": ["直接会议 CTA", "线索磁石 CTA"]
  }
}

响应 (200):

{
  "lead_id": "lead_xyz789",
  "list_id": "uuid",
  "sequence": [
    { "step": 1, "subject": "...", "body": "..." },
    { "step": 2, "subject": "...", "body": "..." },
    { "step": 3, "subject": "...", "body": "..." }
  ],
  "credits_remaining": 94
}

恢复处理： 响应中包含 list_id。如果请求超时或响应被截断，您仍然可以获取结果：调用 GET /api/v1/lists/{list_id} 确认状态，然后调用 GET /api/v1/lists/{list_id}/export?format=json 来检索序列。

批量处理（异步）

为多个潜在客户生成邮件序列（一个列表；每个潜在客户获得一个序列）。立即返回（202）并附带 list_id；处理在后台运行。要获取结果：轮询列表状态，然后调用导出接口。

POST https://app.machfive.io/api/v1/campaigns/{campaign_id}/generate-batch
Authorization: Bearer {MACHFIVE_API_KEY}
Content-Type: application/json

或使用 X-API-Key: {MACHFIVE_API_KEY} 请求头。

{
  "leads": [
    { "name": "张三", "email": "john@acme.com", "company": "Acme 公司", "title": "市场副总裁" },
    { "name": "李四", "email": "jane@beta.com", "company": "Beta 公司", "title": "销售总监" }
  ],
  "options": {
    "list_name": "Q1 推广批量",
    "email_count": 3
  }
}

响应 (202):

{
  "list_id": "uuid",
  "status": "processing",
  "leads_count": 2,
  "message": "批量任务已接受。请轮询列表状态或在 UI 中查看。"
}

列出潜在客户列表

列出工作空间中的潜在客户列表。可选查询参数：campaign_id、status（pending | processing | completed | failed）、limit（默认 50，最大 100）、offset。

GET https://app.machfive.io/api/v1/lists
GET https://app.machfive.io/api/v1/lists?campaign_id={campaign_id}&status=completed&limit=20
Authorization: Bearer {MACHFIVE_API_KEY}

响应 (200): { "lists": [ { "id", "campaign_id", "custom_name", "processing_status", "created_at", "completed_at" }, ... ] }。按 created_at 降序排列。

列表状态（轮询）

轮询直到列表处理完成。使用来自 generate 或 generate-batch 的 list_id。

GET https://app.machfive.io/api/v1/lists/{list_id}
Authorization: Bearer {MACHFIVE_API_KEY}

响应 (200): id、campaign_id、custom_name、processing_status（pending | processing | completed | failed）、created_at、updated_at。当 processing_status === 'completed' 时：包含 leads_count、emails_created、completed_at。当 failed 时：包含 failed_at。如果列表未找到或不在工作空间中，返回 404。

每 10–30 秒轮询一次，直到 processing_status === 'completed' 或 failed。如果 failed，该列表无法导出；请通过提交新的批量任务来重试。

列表导出（获取结果）

状态变为 completed 后，获取处理后的输出。支持 CSV（默认）或 JSON 格式。

GET https://app.machfive.io/api/v1/lists/{list_id}/export?format=csv
GET https://app.machfive.io/api/v1/lists/{list_id}/export?format=json
Authorization: Bearer {MACHFIVE_API_KEY}

• format=csv（默认）：返回处理后的 CSV（与 UI 下载相同），附带 Content-Disposition: attachment; filename="MachFive-{list_id}.csv"。
• format=json：返回 { "leads": [ { "email": "...", "sequence": [ { "step": 1, "subject": "...", "body": "..." }, ... ] }, ... ] }。每个潜在客户在数据存在时可能包含可选的 name、company、title，例如 { "email": "john@acme.com", "name": "张三", "company": "Acme 公司", "title": "市场副总裁", "sequence": [ ... ] }。
• 如果列表尚未完成（请先轮询 GET /lists/:id），返回 409。如果列表未找到或不在工作空间中，返回 404。

批量处理流程： POST generate-batch → 202 + list_id → 轮询 GET /lists/:id 直到 processing_status === 'completed' → GET /lists/:id/export?format=csv 或 json → 将结果返回给用户。

潜在客户字段

每个潜在客户必须包含一个有效的 email；该字段用于在处理过程中映射潜在客户，并在导出时匹配生成的序列与潜在客户（与应用 UI 相同）。所有其他字段都是可选的，但能提升个性化程度。

选项

限制

• 单个潜在客户（同步）： 请求可能需要 5–10 分钟；请使用至少 300 秒（5 分钟）或 600 秒（10 分钟）的客户端超时设置。
• 批量处理（异步）： 立即返回 202；每 10–30 秒轮询一次 GET /api/v1/lists/{list_id}，直到 processing_status 变为 completed 或 failed。工作空间有并发批量任务限制；如果收到 429，请稍后重试。
• 列出列表： 查询参数 limit 默认 50，最大 100；offset 用于分页。

错误

使用示例

“为 Stripe 的销售副总裁生成一封冷启动邮件”
“为这 10 个潜在客户创建推广序列”
“编写一个针对 SaaS 公司市场总监的 3 封邮件序列”

定价

• 免费版：每月 100 积分
• 入门版：每月 2,000 积分
• 增长版：每月 5,000 积分
• 企业版：自定义积分/月
• 1 积分 = 处理 1 个潜在客户

开始使用：https://machfive.io