邮箱查找器 (Email Finder)

当您拥有姓名 + 公司域名时查找工作邮箱。首选 trykitt，失败时回退至 Icypeas。

可独立使用。 仅需 API 密钥。可与 Outreach Magic 配合使用，实现节省信用的去重、持久化存储以及跨会话可用性。

设置

独立模式（无 OM）

仅需 API 密钥。结果打印到标准输出。无需数据库。

密钥	用途
`TRYKITT_API_KEY`	trykitt.ai（瀑布流第一层）— trykitt.ai
`ICYPEAS_API_KEY`	Icypeas（回退层）— app.icypeas.com

python3 scripts/email_finder.py config  # 验证密钥是否已加载
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com
# → 将结果打印到 stdout

与 Outreach Magic 配合使用（去重 + 保存）

添加预查询去重（跳过已在 OM 中的线索）并将结果保存到本地 SQLite 管道。需要 outreachmagic 技能和 pipeline.py login。

密钥	用途
以上所有独立模式密钥 +
`OUTREACHMAGIC_AGENT_KEY`	通过 `pipeline.py login` 登录 OM

python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT
python3 scripts/email_finder.py batch-find --workspace CLIENT --yes --workers 3 --delay 3 input.json

在使用 OM 执行查找/批量查找之前，请确认密钥： python3 <SKILLS>/outreachmagic/scripts/pipeline.py sync-secrets --check --json 或 python3 scripts/email_finder.py config。

密钥通过 Dashboard → pipeline.py sync-secrets 同步。验证来源： python3 scripts/email_finder.py config（*_api_key_source 应为 agent_secrets）。

批量格式

[{"lead_id": 12345, "name": "Jane Doe", "company_domain": "acme.com"}]

生产环境批量默认值

模式	标志
瀑布流	`--workers 3 --delay 3`
仅 IcyPeas	`--workers 2 --delay 3`
仅 TryKitt	`--workers 3`（可选 `--delay 0.2`）

代理规则

使用 OM 时： 在查找前进行检查（check / 带 --save 的 find）。独立模式： 跳过检查 — 直接运行查找。
绝不伪造邮箱。
瀑布流：当两个密钥都设置时，trykitt → Icypeas。
使用 OM 时： 标签 trykitt_attempted / icypeas_attempted；在 MillionVerifier 批量处理后设置 mv_attempted（结果保存在 OM email_verification_status 中）。已找到状态为 leads.email、latest_source 和 email_verification_status。
使用 OM 时： 每一行都需要 lead_id；OM 保存时需要 --workspace。独立模式： 省略 --save 或使用 --no-save 将结果打印到标准输出。
在 --yes 之前运行 batch-find --dry-run 查看跳过计数（线索可能已在 OM 中有邮箱，而 CSV 中的 email 为空）。
batch-find 在每次 API 调用前立即重新检查 OM（跳过自批次开始以来已解决的线索）。
使用 OM 时： batch-find 将 CSV/JSON 写入 outreachmagic/exports/，然后保存到 OM。独立模式： 添加 --skip-om 以在没有 OM 的情况下运行（写入当前工作目录）。
COMPLETE 框显示 IMPORT 和 RELAY（等待快照 — 运行 pipeline.py sync；上传永远不会自动进行）。
积分 — 每个找到的邮箱消耗 1 积分（trykitt / Icypeas）或 每个已验证的邮箱消耗 1 积分（MillionVerifier）。未找到的查询消耗 0 积分。

批量输入

[{"lead_id": 12345, "name": "Jane Doe", "company_domain": "acme.com"}]

可选择包含 "linkedin_url"（当可用时）— trykitt 会利用它提高匹配率。

命令

# 独立模式（无 OM）— 将结果打印到 stdout
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com

# 独立模式批量处理（无 OM）— 将 CSV 写入当前工作目录
python3 scripts/email_finder.py batch-find --skip-om --yes --dry-run input.json

# 使用 OM — 查找 + 去重 + 保存
python3 scripts/email_finder.py find --name "Jane Doe" --domain acme.com --save --workspace CLIENT

# 试运行（显示跳过计数，不消耗 API 额度）
python3 scripts/email_finder.py batch-find --workspace CLIENT --dry-run outreachmagic/batches/leads.json

# 批量处理（查找 + OM 保存）
python3 scripts/email_finder.py batch-find --workspace CLIENT --yes \
  --output-base outreachmagic/exports/emails --workers 3 --delay 3 outreachmagic/batches/leads.json

# 仅 OM 保存 — 在导入失败或使用 --no-save 运行后（接受 .csv 或 .json 批次）
python3 scripts/email_finder.py import-to-om --file outreachmagic/exports/emails.csv --workspace CLIENT

python3 scripts/email_finder.py update --check

# MillionVerifier（可选）
python3 scripts/email_finder.py config
python3 scripts/email_finder.py verify-credits
python3 scripts/email_finder.py verify-bulk --workspace CLIENT --dry-run
python3 scripts/email_finder.py verify-bulk --workspace CLIENT --poll --yes

本地 .env 中的 MILLIONVERIFIER_API_KEY 可能显示为 ***；OM 的 agent_secrets.env 通过 ensure_env_loaded() 覆盖。

通过重新运行相同的 batch-find 命令来恢复崩溃的批次（跳过已完成的 API 行）。如果运行因网络/身份验证错误而失败，请使用 --retry-errors 重新尝试出错的��，而无需删除检查点。

常见工作流程

用户说	您执行
"查找 Patrick 在 stripe.com 的邮箱"	`find --name … --domain stripe.com`（独立模式）或带 `--save --workspace W`（OM 模式）
"为我的 CSV 查找邮箱"（使用 OM）	`batch-find --dry-run` → `batch-find --yes`
"为我的 CSV 查找邮箱"（独立模式）	`batch-find --skip-om --dry-run` → `batch-find --skip-om --yes`
"重试失败的邮箱查找"	使用 `--retry-errors` 参数的相同 `batch-find` 命令

故障排除

ModuleNotFoundError: data_freshness — 在 outreachmagic 上运行 pipeline.py update。
COMPLETE 显示 IMPORT 部分为 ⚠ No import — 结果在磁盘上；运行 import-to-om --file {output-base}.csv --workspace W
CSV 中有邮箱，OM 为空 — 批次保存失败；运行 import-to-om --file {output-base}.csv --workspace W
import-profiles 超时 — 结果在磁盘上；使用 import-to-om 或使用更小的批次重新运行。
IcyPeas 命中率约 10% — 轮询超时；在配置中提高 icypeas_poll_attempts
检查点跳过了所有出错的行 — 使用 --retry-errors 重新运行，或删除 {output-base}.csv / .json 并重新开始。
--provider icypeas 但未设置密钥 — 快速失败；在 app.outreachmagic.io → 设置中添加密钥，然后运行 sync-secrets --check

漏斗

单独使用时即有意义：find / batch-find --skip-om。可与 lead-enrich（研究 → 域名）和 Outreach Magic（节省信用的去重、持久化 SQLite、跨会话可用性）配合使用。了解更多请访问 outreachmagic.io。两个配套工具都会跳过已标记（serper_attempted / trykitt_attempted / icypeas_attempted）的线索。

email-finder (邮箱查找)