email-verification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Email Verification

邮箱验证

Validate emails before sending. Sits between

email-generation

and

campaign-sending

email-generation → email-verification → campaign-sending

在发送邮件前验证邮箱有效性。该环节位于

email-generation

与

campaign-sending

之间：

email-generation → email-verification → campaign-sending

Environment

环境配置

Provider selection and credentials are handled in Step 0 of the workflow.

服务商选择及凭证配置在工作流的第0步完成。

Inputs

输入项

Input	Required	Source
Contact CSV with email column	yes	From `email-generation` output or any CSV
Sequencer campaign IDs	no	From `campaign-sending` — only if cleaning uploaded leads

输入内容	是否必填	来源
包含邮箱列的联系人CSV文件	是	来自 `email-generation` 的输出或任意CSV文件
序列营销活动ID	否	来自 `campaign-sending` — 仅在需要清理已上传的潜在客户时使用

Workflow

工作流

Step 0: Confirm provider and learn API

步骤0：确认服务商并了解API

Ask the user which email verification provider they want to use.
Fetch or read the provider's API documentation and identify:
- Credit check endpoint
- Single email validation endpoint
- Required input fields and authentication method
- Rate limits and request constraints
- Response format (status, sub_status)
- Status values and which to keep vs remove
Ask for their API credentials and confirm access

询问用户想要使用的邮箱验证服务商。
获取或查阅该服务商的API文档，明确以下信息：
- 余额查询接口
- 单个邮箱验证接口
- 必填输入字段及认证方式
- 请求速率限制及约束条件
- 响应格式（状态码、子状态码）
- 状态值含义，以及需要保留和移除的状态类别
向用户索要API凭证并确认可正常访问

Step 1: Check API access and credits

步骤1：检查API访问权限及余额

Call the provider's credit check endpoint
Count unique emails in the input CSV
If credits < unique emails, warn the user and ask whether to proceed with partial validation or stop

调用服务商的余额查询接口
统计输入CSV中的唯一邮箱数量
若余额 < 唯一邮箱数量，向用户发出警告，并询问是否继续进行部分验证或终止操作

Step 2: Extract and deduplicate emails

步骤2：提取并去重邮箱

Read the input CSV, auto-detect the email column (common names:
```
email
```
,
```
Email
```
,
```
email_address
```
)
Build a set of unique email addresses
Skip rows with empty/missing email

Report:

{N} unique emails to validate, {M} rows without email skipped

读取输入CSV文件，自动识别邮箱列（常见列名：
```
email
```
、
```
Email
```
、
```
email_address
```
）
生成唯一邮箱地址集合
跳过邮箱为空/缺失的行

生成报告：

{N}个待验证的唯一邮箱，{M}行因无邮箱被跳过

Step 3: Validate emails

步骤3：验证邮箱有效性

For each unique email, call the provider's validation endpoint:

Respect the provider's rate limits (from Step 0)
Print progress every 50 emails
Store results as
```
{email: {status, sub_status}}
```
On error (timeout, JSON parse failure), mark as
```
unknown
```

对每个唯一邮箱，调用服务商的验证接口：

遵守步骤0中确认的服务商请求速率限制
每验证50个邮箱打印一次进度
将结果存储为
```
{email: {status, sub_status}}
```
格式
若出现错误（超时、JSON解析失败），标记为
```
unknown
```

Step 4: Categorize and report

步骤4：分类并生成报告

Group results by the provider's status values. Use the status mapping identified in Step 0 to determine which emails to keep and which to remove.

General guidance (confirm against provider docs):

Action	Typical statuses
Keep	`valid` , `catch-all` (flag in report)
Remove	`invalid` , `do_not_mail` , `abuse` , `unknown` , `spamtrap`

Present summary table with counts per status, then list all emails to remove with their status and sub_status.

根据服务商的状态值对结果进行分组。使用步骤0中确定的状态映射规则，判断哪些邮箱需要保留、哪些需要移除。

通用参考规则（需结合服务商文档确认）：

操作	典型状态值
保留	`valid` 、 `catch-all` （需在报告中标记）
移除	`invalid` 、 `do_not_mail` 、 `abuse` 、 `unknown` 、 `spamtrap`

生成包含各状态数量的汇总表格，随后列出所有需移除的邮箱及其状态和子状态。

Step 5: Output cleaned CSV

步骤5：输出清理后的CSV文件

Filter the original CSV: keep only rows where email status maps to "keep"
Write cleaned CSV to same directory as input, named
```
{original_name}_verified.csv
```
Save full validation results to
```
{original_name}_verification_results.json
```
for reference

Report:

{kept} emails kept, {removed} removed, {catch_all} catch-all (flagged)

过滤原始CSV：仅保留邮箱状态为“保留”的行
将清理后的CSV写入输入文件所在目录，命名为
```
{original_name}_verified.csv
```
将完整验证结果保存为
```
{original_name}_verification_results.json
```
，供后续参考

生成报告：

保留{kept}个邮箱，移除{removed}个邮箱，{catch_all}个全域邮箱（已标记）

Step 6: Clean from sequencer (optional)

步骤6：从序列营销工具中清理（可选）

If the user provides sequencer campaign IDs:

Ask which sequencer they use (Instantly, etc.) and read its API docs from
```
skills/campaign-sending/references/
```
For each removed email, call the sequencer's lead deletion endpoint
Respect rate limits
Report:
```
{N} leads removed from sequencer
```

If no campaigns are provided, skip this step and note that the user should remove bad emails manually or re-upload with the cleaned CSV.

若用户提供了序列营销活动ID：

询问用户使用的序列营销工具（如Instantly等），并从
```
skills/campaign-sending/references/
```
中读取其API文档
对每个需移除的邮箱，调用序列营销工具的潜在客户删除接口
遵守速率限制

生成报告：

已从序列营销工具中移除{N}个潜在客户

若未提供活动ID，则跳过此步骤，并提示用户需手动移除无效邮箱，或重新上传清理后的CSV文件。

Output

输出项

File	Contents
`*_verified.csv`	Cleaned CSV with only valid emails
`*_verification_results.json`	Full validation results for all emails
Console report	Summary table + list of removed emails

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

API References

API参考文档

Provider API docs are fetched or read during Step 0. No pre-configured provider docs are bundled — add them to

references/

as needed.

服务商的API文档会在步骤0中获取或查阅。未预配置服务商文档，可根据需要将其添加至

references/

目录。