介绍
# MachFive - AI Cold Email Generator
根据潜在客户数据生成个性化的冷邮件序列。MachFive 使用 AI 调研潜在客户并精心制作独特、相关的推广内容——而非使用模板。
## 设置
1. 在 https://app.machfive.io/settings 获取您的 API 密钥（Integrations → API Keys） 2. 在您的环境中设置 `MACHFIVE_API_KEY`
## 营销活动 ID (Campaign 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”），代理可以将其存储给工作区。
## 端点 (Endpoints)
### 列出营销活动（生成前发现）
列出工作区中的营销活动，以便代理在用户未提供名称或 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)：** ```json { "campaigns": [ { "id": "cb1bbb14-e576-4d8f-a8f3-6fa929076fd8", "name": "SaaS Q1 Outreach", "created_at": "2025-01-15T12:00:00Z" }, { "id": "a1b2c3d4-...", "name": "Enterprise Leads", "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}` 请求头。 ```json { "lead": { "name": "John Smith", "title": "VP of Marketing", "company": "Acme Corp", "email": "[email protected]", "company_website": "https://acme.com", "linkedin_url": "https://linkedin.com/in/johnsmith" }, "options": { "list_name": "Q1 Outreach", "email_count": 3, "email_signature": "Best,\nYour Name", "approved_ctas": ["Direct Meeting CTA", "Lead Magnet CTA"] } } ```
**响应 (200)：** ```json { "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}` 请求头。 ```json { "leads": [ { "name": "John Smith", "email": "[email protected]", "company": "Acme Corp", "title": "VP Marketing" }, { "name": "Jane Doe", "email": "[email protected]", "company": "Beta Inc", "title": "Director Sales" } ], "options": { "list_name": "Q1 Outreach Batch", "email_count": 3 } } ```
**响应 (202)：** ```json { "list_id": "uuid", "status": "processing", "leads_count": 2, "message": "Batch accepted. Poll list status or open in 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_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": "[email protected]", "name": "John Smith", "company": "Acme Corp", "title": "VP Marketing", "sequence": [ ... ] }`。 - **409** 如果列表尚未完成（请先轮询 GET /lists/:id）。**404** 如果列表未找到或不在工作区中。
**批量流程：** POST generate-batch → 202 + list_id → 轮询 GET /lists/:id 直到 `processing_status === 'completed'` → GET /lists/:id/export?format=csv 或 json → 向用户返回结果。
## 潜在客户字段
每个潜在客户必须包含一个有效的 **`email`**；它用于在处理过程中映射潜在客户，并在导出中将生成的序列与潜在客户匹配（与应用 UI 相同）。所有其他字段都是可选的，但有助于提高个性化程度。
| 字段 | 必填 | 描述 | |-------|----------|-------------| | `email` | **是** | 潜在客户的电子邮件地址；用于在处理和导出过程中映射潜在客户 | | `name` | 否 | 全名或名字（有助于提高个性化） | | `company` | 否 | 公司名称（有助于提高个性化） | | `title` | 否 | 职位（有助于提高个性化） | | `company_website` | 否 | 用于调研的公司 URL | | `linkedin_url` | 否 | LinkedIn 个人资料，用于更深度的个性化 |
## 选项
| 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | `list_name` | string | Auto | MachFive UI 中此列表的显示名称 | | `email_count` | number | 3 | 每个潜在客户的邮件数 (1-5) | | `email_signature` | string | None | 附加到邮件的签名 | | `campaign_angle` | string | None | 个性化上下文 | | `approved_ctas` | array | 来自营销活动 | 要使用的 CTA（省略以使用营销活动默认值） |
## 限制
- **单个潜在客户（同步）：** 请求可能耗时 5-10 分钟；请使用至少 300 秒（5 分钟）或 600 秒（10 分钟）的客户端超时。 - **批量（异步）：** 立即返回 202；每 10–30 秒轮询 **GET /api/v1/lists/{list_id}**，直到 `processing_status` 为 `completed` 或 `failed`。工作区有并发批处理限制；如果您收到 **429**，请稍后重试。 - **列出列表：** 查询参数 `limit` 默认 50，最大 100；`offset` 用于分页。
## 错误
| 代码 | 错误 | 描述 | |------|-------|-------------| | 400 | BAD_REQUEST | 无效的 JSON，缺少 `lead`/`leads`，或缺少/无效的潜在客户 `email`；或营销活动没有向量存储 | | 401 | UNAUTHORIZED | 无效或缺少 API 密钥 | | 402 | INSUFFICIENT_CREDITS | 额度不足 | | 403 | FORBIDDEN | 营销活动不在您的工作区中 | | 404 | NOT_FOUND | 营销活动或列表不存在 | | 409 | NOT_READY | 在列表完成前调用了导出（请先轮询 GET /lists/:id）| | 429 | WORKSPACE_LIMIT | 并发批处理任务过多；请稍后重试 |
## 使用示例
“为 Stripe 的销售副总裁生成一封冷邮件” “为这 10 个潜在客户创建推广序列” “编写一个针对 SaaS 公司营销总监的 3 封邮件序列”
## 定价
- 免费版：100 额度/月 - 入门版：2,000 额度/月 - 成长版：5,000 额度/月 - 企业版：自定义额度/月 - 1 额度 = 处理 1 个潜在客户
开始使用：https://machfive.io