apify-verified-email-finder

已验证邮箱查找工具

将用户输入路由到合适的 Apify Actor，并在单次运行中启用潜在客户信息补全和邮箱验证附加功能，从而返回已验证的商务邮箱列表。无需第三方验证工具（Hunter、NeverBounce、Apollo）——验证在同一次 Actor 运行中完成。

先决条件

（无需提前检查）

此技能支持两种执行路径。请选择符合你环境的路径——第 4 步和第 5 步提供了两种路径的命令。

MCP 路径（Claude 会话中的默认路径，推荐）。 如果已连接 Apify MCP 服务，则无需设置——通过用户的 Apify 账户进行身份验证。使用 call-actor 和 get-dataset-items MCP 工具。

脚本路径（CLI / 定时任务 / 非 Claude 执行）。 需要：

• 包含 APIFY_TOKEN 的 .env 文件
• Node.js 20.6+（支持原生 --env-file）

工作流

复制此清单并跟踪进度：

Task Progress:
- [ ] Step 1: Collect the six required anchor inputs
- [ ] Step 2: Route to the correct Actor (confirm if ambiguous)
- [ ] Step 3: Build the Actor input (verification always ON)
- [ ] Step 4: Run the Actor and wait
- [ ] Step 5: Apply the result-scope filter, deduplicate, and render

步骤 1：收集六项必需的锚点输入

在调用任何 Actor 之前，一次性询问以下六项。不要在这一轮中混入特定 Actor 的可选字段（国家/地区代码、语言、最大页数）——后续再询问这些内容。

1. 你要从什么信息开始？ — location query / SERP keyword / URL list。这决定路由方式。
2. 具体输入内容 — 地点字符串、关键词或 URL 本身。
3. 部门筛选条件 — 以下一项或多项：c_suite、product、engineering_technical、design、education、finance、human_resources、information_technology、legal、marketing、medical_health、operations、sales、consulting。默认值为 any（数组留空），但每次都要询问。
4. 每个域名 / 企业的最大联系人数量 — 作为 maximumLeadsEnrichmentRecords 传入。默认值为 3，但每次都要询问。
5. 输出格式 — CSV 或 JSON。每次都要询问。
6. 结果范围 — 要在交付内容中保留哪些潜在客户。Actor 的运行方式始终相同（始终启用验证）；此项仅控制运行后的筛选。选择一项：
   • verified-only（默认）——仅保留 emailVerification.result == "ok" 的潜在客户。最适合冷邮件。
   • verified-plus-catchall ——保留 ok 和 catch_all。catch-all 邮箱通常可以投递，但无法验证。
   • all-emails ——保留任何 email 非空的潜在客户，不论验证状态如何。
   • with-phone ——保留任何电话号码非空的潜在客户，不论邮箱状态如何。适用于电话营销活动。
   • everything ——保留 Actor 返回的所有潜在客户，包括信息不完整的记录。

第 2 步：选择正确的 Actor

检查锚点 #1 并选择 Actor。

用户需要以什么开头	Actor ID	适用场景
地点 + 业务类型（“柏林的牙医”）	compass/crawler-google-places	从 Maps 列表获取本地潜在客户名单；用户还想要地址 / 电话 / 营业时间时最适用
关键词 / 搜索查询（“最佳 CRM 软件”）	apify/google-search-scraper	从 Google 为某个主题排名的各个网站中获取联系人
现成的 URL 列表（粘贴内容、文件路径）	vdrmota/contact-info-scraper	用户已有域名；由于无需发现步骤，这是成本最低的途径

这三个 Actor 共用相同的三个附加字段，因此各条途径的验证行为完全一致。

决策示例

用户的说法	途径
“慕尼黑的牙医” / “布拉格的律师”	Maps
“‘AI Agent 构建器’搜索结果排名靠前的网站中的营销联系人”	Search
“查找这 5 个 URL 的邮箱：acme-co.example、demo-co.example……”	URL 列表
“查找财富 500 强公司的 HR 联系人”	**询问：**搜索“Fortune 500 HR”的 SERP，还是 URL 列表？
“查找柏林 SaaS 公司的联系人”	**询问：**通过 Maps 搜索“柏林的 SaaS 公司”，还是通过 SERP 搜索“SaaS companies Berlin”？企业需在 Google Maps 上列出时，Maps 最适用。
（用户同时粘贴了 SERP 关键词和 URL 列表）	**询问：**运行其中一种途径、另一种途径，还是都运行并分别交付？

歧义规则：如果锚点 #1 不明确，运行前先提出一个后续问题。绝不要因为猜测途径而浪费 Actor 的计算资源。

**混合交付：**如果用户明确要求在一项交付内容中包含两种途径，则运行两个 Actor 并合并结果。Source 列可清楚显示混合来源；对合并后的输出按邮箱去重。

第 3 步：构建 Actor 输入

无论选择哪个 Actor，都要始终设置以下三个字段。

字段	值
maximumLeadsEnrichmentRecords	锚点 #4（默认值为 3，最小值为 1）
leadsEnrichmentDepartments	将锚点 #3 设为数组；如果是“任意”，则设为 []
verifyLeadsEnrichmentEmails	true（始终如此）——这是安全措施，绝不要设为 false

每个 Actor 的完整输入参数和示例负载见 reference/apify-actor-usage.md。

**URL 列表预验证：**向 vdrmota/contact-info-scraper 提交 URL 之前，解析每个 URL 并检查其是否为 http/https 且可解析。跳过的条目必须在输出中标记为 skipped — invalid URL，绝不能静默丢弃。

第 4 步：运行 Actor

使用潜在客户信息增强功能运行 Maps 和 SERP 时，每个查询可能需要几分钟。大型任务请延长超时时间。

MCP 路径（Claude 会话中的默认方式）：

调用 call-actor 工具：

• actor：三个 Actor ID 之一（compass/crawler-google-places、apify/google-search-scraper、vdrmota/contact-info-scraper）
• input：第 3 步中的 JSON 负载
• callOptions：预算充足时使用 {"timeout": 1800, "memory": 4096}

该工具会返回 runId 和 datasetId。如果 status 仍为 RUNNING，则使用 get-actor-run 轮询（waitSecs 最长为 45），直到状态变为 SUCCEEDED。保存这两个 ID，以便写入 run_metadata.json 辅助文件。

脚本路径（CLI / 定时任务）：

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_verified-emails.csv \
  --format csv \
  --timeout 900

对于 JSON，请使用 --format json。脚本会将原始数据集写入磁盘；第 5 步仍会在此基础上应用误匹配过滤和范围过滤。

第 5 步：筛选、去重并呈现

获取数据集：

• MCP 路径： 使用第 4 步中的 datasetId 调用 get-dataset-items。使用 fields 参数（例如 title,searchString,countryCode,city,address,phone,website,leadsEnrichment）和 clean: true，以减小响应内容。对于仍超过响应上限的数据集，直接通过 curl https://api.apify.com/v2/datasets/<id>/items?fields=...&clean=true 获取，并通过管道传给 jq。
• 脚本路径： 原始数据集已保存在第 4 步所用的文件中。

每条记录都包含业务字段，以及一个 leadsEnrichment 数组（Maps、SERP）或顶层的潜在客户字段（URL 列表）。每条潜在客户记录都包含一个 departments 数组、一个 companyWebsite，以及一个 emailVerification 对象，其中 result 为（ok / invalid / disposable / catch_all / unknown / error），quality 为（good / risky / bad）。

• 过滤错误匹配（必须始终执行）。 必须首先应用此过滤器，再应用任何其他过滤器。当没有本地匹配项时，潜在客户信息补全服务可能会返回全局回退结果（已观察到的真实案例：一家美国动物园的 CFO，其 companyWebsite=zoo.org 被错误归到 8 家无关的波兰动物园，因为匹配器依据 zoo 子串进行了匹配）。移除 companyWebsite 主机名与来源 URL 主机名不一致的所有潜在客户（去掉 https?://、开头的 www. 和 / 之后的所有内容；转换为小写）。在 run_metadata.json 中统计移除数量；如果不为零，须在交付物标题中注明。

• 按结果范围过滤（锚点 #6）。第二步应用。

  范围	保留行的逻辑
  verified-only	emailVerification.result == "ok"
  verified-plus-catchall	emailVerification.result in {"ok", "catch_all"}
  all-emails	email 非空（任何结果，包括缺少验证信息的情况）
  with-phone	phone（或公司电话）非空（无论是否有电子邮件）
  everything	保留所有潜在客户，不过滤

• 去重： 按小写电子邮件分组；保留首次出现的记录，并在同一电子邮件出现在多个来源时合并 Source Query or URL。对于没有电子邮件的 with-phone 行，按小写电话号码去重。

• 显示空结果： 如果部门过滤器（锚点 #3）使某个域名没有匹配的潜在客户，则为该域名添加一行，其中 Email = ""，且 Email Verification Status = "no leads matched filter"。不要悄悄丢弃该域名。此操作与上述结果范围过滤器分开执行——空域名行会在范围过滤前插入，并始终显示。

输出行的架构（16 列，包含 Departments）以及各格式的呈现详情见 reference/output-formats.md。

示例

• Maps：examples/example-maps-input.md
• SERP：examples/example-search-input.md
• URL 列表：examples/example-url-list-input.md

质量规则（始终遵守）

• 防护措施： 绝不提交 verifyLeadsEnrichmentEmails: false 的运行。
• 来源与可追溯性： 每一行都填写 Source 列；在 run_metadata.json 中保留 Apify runId 和 datasetId。
• 不得编造： 数据集缺失的字段保持空白。
• 交付物标题透明： 说明当前使用的结果范围和错误匹配移除数量；并提出可按其他范围重新呈现。
• 确认歧义： 如果锚点 #1 不明确，运行前先询问。

费用与定价

仅对确定性结果（ok / invalid / disposable）收取电子邮件验证费用；catch_all / unknown / error 免费。潜在客户信息补全按成功提取的潜在客户数量收费。请查看 Apify 控制台了解实时价格（价格会因订阅层级而异，并随时间变化）。

错误处理

请参阅 reference/troubleshooting.md。