email-verification

电子邮件验证

发送前验证电子邮件地址。此步骤位于 email-generation 和 campaign-sending 之间：

email-generation → email-verification → campaign-sending

环境

提供商选择和凭据在工作流的第 0 步处理。

输入

输入	必填	来源
含电子邮件列的联系人 CSV	是	来自 email-generation 输出，或任意 CSV
Sequencer 活动 ID	否	来自 campaign-sending——仅在清理已上传的潜在客户时需要

工作流

第 0 步：确认提供商并了解 API

1. 询问用户想使用哪家电子邮件验证提供商。
2. 获取或阅读提供商的 API 文档，并确认：
   • 积分查询端点
   • 单个电子邮件验证端点
   • 必填输入字段和身份验证方式
   • 速率限制和请求约束
   • 响应格式（status、sub_status）
   • 状态值，以及哪些应保留、哪些应移除
3. 询问用户的 API 凭据并确认访问权限

第 1 步：检查 API 访问权限和积分

1. 调用提供商的积分查询端点
2. 统计输入 CSV 中的唯一电子邮件地址
3. 如果积分少于唯一电子邮件地址数，提醒用户，并询问是继续进行部分验证还是停止

第 2 步：提取并去重电子邮件地址

1. 读取输入 CSV，自动检测电子邮件列（常见名称：email、Email、email_address）
2. 创建唯一电子邮件地址集合
3. 跳过电子邮件地址为空或缺失的行
4. 报告：待验证的唯一电子邮件地址共 {N} 个，跳过无电子邮件地址的行共 {M} 行

第 3 步：验证电子邮件地址

对每个唯一电子邮件地址，调用提供商的验证端点：

• 遵守提供商的速率限制（见第 0 步）
• 每验证 50 个电子邮件地址打印一次进度
• 将结果保存为 {email: {status, sub_status}}
• 发生错误（超时、JSON 解析失败）时，将状态标记为 unknown

第 4 步：分类并报告

按提供商的状态值对结果分组。根据第 0 步确认的状态映射，确定哪些电子邮件地址应保留，哪些应移除。

一般建议（请根据提供商文档确认）：

操作	常见状态
保留	valid
移除	invalid、do_not_mail、abuse、catch-all、unknown、spamtrap

移除 catch-all 地址，不要保留。 Catch-all 域名会接受发送至任意地址的邮件，因此提供商无法确认具体邮箱是否存在。这些地址的退信率相当高，而退信会损害整个活动的发件人信誉。切勿将 catch-all 地址上传至 sequencer。

提供包含各状态数量的汇总表，然后列出所有待移除的电子邮件地址及其 status 和 sub_status。

第 5 步：输出清理后的 CSV

1. 筛选原始 CSV：仅保留状态映射为“保留”的电子邮件地址所在行
2. 将清理后的 CSV 写入与输入文件相同的目录，命名为 {original_name}_verified.csv
3. 将完整验证结果保存至 {original_name}_verification_results.json，以供参考
4. 报告：保留 {kept} 个电子邮件地址，移除 {removed} 个（按状态细分，并注明其中有多少个为 catch-all）

第 6 步：从 sequencer 中清理（可选）

如果用户提供了 sequencer 活动 ID：

1. 询问用户使用的是哪个 sequencer（Instantly 等），并从 skills/campaign-sending/references/ 阅读其 API 文档
2. 对每个待移除的电子邮件地址，调用 sequencer 的潜在客户删除端点
3. 遵守速率限制
4. 报告：已从 sequencer 中移除 {N} 个潜在客户

如果用户未提供活动 ID，则跳过此步骤，并提醒用户手动移除无效电子邮件地址，或使用清理后的 CSV 重新上传。

输出

文件	内容
*_verified.csv	仅包含有效电子邮件地址的清理后 CSV
*_verification_results.json	所有电子邮件地址的完整验证结果
控制台报告	汇总表 + 已移除的电子邮件地址列表

API 参考

提供商的 API 文档将在第 0 步获取或阅读。未随附预先配置的提供商文档——按需将其添加到 references/。