Instantly 营销活动构建器

通过 API v2 构建和管理 Instantly.ai 冷邮件营销活动。

认证（Auth）

所有请求均需包含以下头信息：

Authorization: Bearer {INSTANTLY_API_KEY}
Content-Type: application/json
Base URL: https://api.instantly.ai

工作流程 — 请按此顺序执行

步骤 1：创建营销活动

POST /api/v2/campaigns

必填字段：

• name — 营销活动名称
• email_list — 发件人邮箱地址数组
• sequences — 消息步骤（参见步骤 2）

可选但强烈建议填写的字段：

• daily_limit — 每日最大发送邮件数
• daily_max_leads — 每日最多触达的新线索数
• email_gap — 两次发送之间的间隔（单位：秒）
• open_tracking、link_tracking — 布尔值
• stop_on_reply、stop_on_auto_reply、stop_for_company — 布尔值
• text_only、first_email_text_only — 布尔值
• campaign_schedule — 对象，包含 start_date、end_date 和 schedules（时间/日期/时区）

步骤 2：配置消息序列（sequences）

sequences 字段为数组，但仅使用第一个元素。请将所有步骤统一置于该数组项中。

每个步骤包含以下字段：

• type：固定为 "email"
• delay：数字类型（本步骤前等待时长）
• delay_unit：取值为 "minutes"、"hours" 或 "days"
• variants：消息变体数组（用于 A/B 测试）

每个变体包含以下字段：

• subject：邮件主题行
• body：邮件正文（支持 HTML 或纯文本）
• v_disabled：布尔值（设为 true 可禁用该变体）

主题与正文中变量的语法：{{variableName}}

内置变量：{{firstName}}、{{lastName}}、{{companyName}}、{{email}}、{{phone}}、{{website}}

自定义变量：任意合法变量名，例如 {{city}}、{{offer}}、{{icebreaker}}

示例：一个三步 ARA 序列：

{
  "sequences": [
    {
      "steps": [
        {
          "type": "email",
          "delay": 0,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "{{firstName}}, {{offer}}",
              "body": "Bonjour {{firstName}},nn{{icebreaker}}nnNous proposons {{offer}} pour les entreprises à {{city}}.nnCordialement"
            }
          ]
        },
        {
          "type": "email",
          "delay": 3,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "Re: {{firstName}}, suite à mon message",
              "body": "{{firstName}},nnJe me permets de relancer..."
            }
          ]
        },
        {
          "type": "email",
          "delay": 5,
          "delay_unit": "days",
          "variants": [
            {
              "subject": "Dernière relance {{firstName}}",
              "body": "{{firstName}},nnDernier message de ma part..."
            }
          ]
        }
      ]
    }
  ]
}

步骤 3：声明营销活动变量

POST /api/v2/campaigns/{campaign_id}/variables

{
  "variables": ["firstName", "companyName", "city", "offer", "icebreaker"]
}

在此处声明序列中使用的所有自定义变量名。

步骤 4：添加线索（Leads）

单条线索：POST /api/v2/leads

{
  "email": "lead@example.com",
  "first_name": "Jean",
  "last_name": "Dupont",
  "company_name": "Acme SAS",
  "campaign": "campaign-uuid",
  "custom_variables": {
    "city": "Paris",
    "offer": "audit IA gratuit",
    "icebreaker": "J'ai vu votre post LinkedIn sur la transformation digitale"
  }
}

批量导入（每次最多 1000 条）：POST /api/v2/leads/add

{
  "campaign_id": "campaign-uuid",
  "leads": [
    {
      "email": "lead1@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "company_name": "Acme SAS",
      "custom_variables": { "city": "Paris", "offer": "audit IA gratuit" }
    },
    {
      "email": "lead2@example.com",
      "first_name": "Marie",
      "last_name": "Martin",
      "company_name": "Beta Corp",
      "custom_variables": { "city": "Lyon", "offer": "démo chatbot" }
    }
  ]
}

注意事项：

• 只能指定 campaign_id 或 list_id 中的一个，不可同时提供两者
• 若在单条线索请求中提供了 campaign 字段，则必须提供 email
• 去重标识符：skip_if_in_campaign、skip_if_in_workspace、skip_if_in_list

步骤 5：启用营销活动

POST /api/v2/campaigns/{campaign_id}/activate

仅当线索已添加且消息序列已配置完毕后，方可启用营销活动。

修改已有营销活动

PATCH /api/v2/campaigns/{campaign_id}

结构与创建时的 sequences 相同。可用于在营销活动创建完成后更新消息内容。

A/B 测试

为每个步骤添加多个变体：

{
  "type": "email",
  "delay": 0,
  "delay_unit": "days",
  "variants": [
    {
      "subject": "Version A — {{firstName}}",
      "body": "Approche directe...",
      "v_disabled": false
    },
    {
      "subject": "Version B — {{firstName}}",
      "body": "Approche soft...",
      "v_disabled": false
    }
  ]
}

必需的 API 权限范围（Scopes）

• 线索（Leads）：leads:create、leads:all、all:create 或 all:all
• 营销活动（Campaigns）：campaigns:create、campaigns:all、all:create 或 all:all
• 营销活动更新（Campaign update）：campaigns:update、campaigns:all、all:update 或 all:all

启用前检查清单

1. 已创建营销活动，并在主题与正文中正确使用了序列及变量
2. 已通过 /campaigns/{id}/variables 接口声明全部变量
3. 已添加线索，且其 custom_variables 与序列中使用的变量完全匹配
4. 发件邮箱已完成配置并完成预热（warm-up）
5. 如需定时发送，已正确设置 campaign_schedule
6. 已通过 /campaigns/{id}/activate 接口启用营销活动