instantly-api

Instantly API

通过 ColdIQ 转售的 Instantly 端点 /v1/instantly/* 在 Instantly 中创建营销活动、导入潜在客户并获取分析数据（保留 Instantly v2 路径，只需一个 ColdIQ 密钥；BYOK — 连接你自己的 Instantly 账户，免费，无需 ColdIQ 积分）。

ColdIQ Marketplace 端点

任务	方法	路径	积分	端点 ID	备注
创建营销活动	POST	/v1/instantly/campaigns	免费	instantly.campaigns.create	使用 ColdIQ 默认值
列出营销活动	GET	/v1/instantly/campaigns	免费	instantly.campaigns.list	按状态筛选
获取营销活动	GET	/v1/instantly/campaigns/{id}	免费	instantly.campaigns.get	验证序列
更新营销活动	PATCH	/v1/instantly/campaigns/{id}	免费	instantly.campaigns.patch	部分更新
激活营销活动	POST	/v1/instantly/campaigns/{id}/activate	免费	instantly.campaigns.activate	空请求体 {}；请向用户确认
暂停营销活动	POST	/v1/instantly/campaigns/{id}/pause	免费	instantly.campaigns.pause	空请求体 {}
添加单个潜在客户	POST	/v1/instantly/leads	免费	instantly.leads.create	使用 campaign，而不是 campaign_id
批量添加潜在客户	POST	/v1/instantly/leads/add	免费	instantly.leads.add
列出潜在客户	POST	/v1/instantly/leads/list	免费	instantly.leads.list	GET /leads 会返回 404
营销活动分析	GET	/v1/instantly/campaigns/analytics	免费	instantly.campaigns.analytics	回复/打开/退信
每日分析	GET	/v1/instantly/campaigns/analytics/daily	免费	instantly.campaigns.analytics.daily	按天统计
验证电子邮件	POST	/v1/instantly/email-verification	免费	instantly.email_verification.create

推荐的营销活动设置

每个新营销活动都应采用以送达率为先的基线设置：

{
  "email_gap": 15, "random_wait_max": 7, "text_only": true, "first_email_text_only": true,
  "daily_limit": 9999, "stop_on_reply": true, "match_lead_esp": true,
  "link_tracking": false, "open_tracking": false,
  "campaign_schedule": { "schedules": [{ "name": "Weekday schedule",
    "timing": { "from": "08:00", "to": "14:00" },
    "days": { "1": true, "2": true, "3": true, "4": true, "5": false },
    "timezone": "America/Detroit" }] }
}

text_only、不进行链接/打开跟踪，并匹配 ESP，均可最大限度提升送达率。

注意事项（请先阅读）

1. 时区： 使用 America/Detroit，不要使用 America/New_York（Instantly 会拒绝 New_York）。
2. 计划日期： 从星期日开始，索引从 0 起（0=星期日 … 6=星期六）。
3. 激活/暂停： 发送空 JSON 请求体 {}。
4. 删除潜在客户： 不发送请求体，也不发送 Content-Type 标头。
5. 列出潜在客户： 使用 POST /v1/instantly/leads/list（GET 会返回 404）。
6. 潜在客户字段名称： 使用 campaign（UUID），不要使用 campaign_id——错误的键会在不提示的情况下将潜在客户添加到组织池中，而不会关联到营销活动。
7. HTML 转义： 正文中的 > 必须写为 >（例如“Predictable > random”）。
8. 潜在客户去重： 默认情况下，潜在客户会跨营销活动去重；设置 skip_if_in_campaign: false 可强制添加。

HTML 电子邮件格式

即使设置了 text_only: true，Instantly 也会存储 HTML <div>。每行都放在单独的 <div> 中；空行使用 <div><br /></div>；不要使用 <p>；对 >/< 进行 HTML 编码；签名使用 <div>{{accountSignature}}</div>。

import html
def to_instantly_html(plain):
    return ''.join('<div><br /></div>' if not l.strip() else f'<div>{html.escape(l.strip())}</div>'
                   for l in plain.strip().split('\n'))

变量

核心变量（根据潜在客户信息自动填充）：{{firstName}}、{{lastName}}、{{companyName}}、{{email}}、 {{website}}、{{personalization}}、{{accountSignature}}。自定义变量：潜在客户 payload 中的任何键都会变为 {{key}}（例如 {{Idea1}}、{{Idea2}}、{{Idea3}}、{{SL}}）。 旋转文本：{{RANDOM|Hey|Hi|Hello}} {{firstName}},。

工作流

完整的营销活动发布

1. 使用 ColdIQ 默认设置和序列创建营销活动。 → POST /v1/instantly/campaigns · 免费 · instantly.campaigns.create
2. 使用载荷变量添加潜在客户（循环添加或批量添加）。 → POST /v1/instantly/leads · 免费 · instantly.leads.create

   { "campaign": "campaign-uuid", "email": "[email protected]", "first_name": "John",
     "company_name": "Acme", "payload": { "Idea1": "...", "Idea2": "...", "Idea3": "..." } }
   

3. 确认序列看起来正确。 → GET /v1/instantly/campaigns/{id} · 免费 · instantly.campaigns.get
4. 连接发送账户（Instantly 界面），然后激活——务必先征得用户确认。 → POST /v1/instantly/campaigns/{id}/activate · 免费 · instantly.campaigns.activate

效果检查

1. 汇总统计数据。 → GET /v1/instantly/campaigns/analytics · 免费 · instantly.campaigns.analytics
2. 每日趋势。 → GET /v1/instantly/campaigns/analytics/daily · 免费 · instantly.campaigns.analytics.daily

基准

指标	淘汰	保留	扩大规模
正向回复率	<1%	2–5%	>5%
每条正向回复对应的邮件数	>5,000	1,000–3,000	<1,000
会议预约率	<0.5%	1–2%	>2%

一种可靠的高绩效做法：将 3 个 AI 生成的营销活动创意（{{Idea1}}/{{Idea2}}/{{Idea3}}）作为个性化载荷。每个变体发送 200 封以上后：淘汰回复率 <1% 的变体，将表现最好的 2–3 个分支拓展（优胜方案/迭代/实验按 70/20/10 分配）。