Email Finder

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
# → 將結果輸出至標準輸出

搭配 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 進行 find/batch 之前，請確認金鑰： python3 <SKILLS>/outreachmagic/scripts/pipeline.py sync-secrets --check --json 或 python3 scripts/email_finder.py config。

金鑰透過儀表板 → 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)

代理規則

1. 使用 OM 時： 在查找前檢查 (check / 使用 --save 的 find)。獨立運行： 跳過檢查 — 直接執行 find。
2. 絕不偽造電子郵件。
3. 瀑布式：當兩個金鑰都設定時，trykitt → Icypeas。
4. 使用 OM 時： 標籤 trykitt_attempted / icypeas_attempted；百萬驗證器批量處理後加上 mv_attempted（結果存在 OM 的 email_verification_status 中）。找到的狀態為 leads.email、latest_source 和 email_verification_status。
5. 使用 OM 時： 每一行都需要 lead_id；OM 儲存需要 --workspace。獨立運行： 省略 --save 或使用 --no-save 將結果輸出至標準輸出。
6. 在執行 --yes 之前先執行 batch-find --dry-run 以查看跳過計數（潛在客戶在 OM 中可能已有電子郵件，而 CSV 中的 email 欄位為空）。
7. batch-find 在每次 API 調用前會立即重新檢查 OM（跳過自批次開始後已解析的潛在客戶）。
8. 使用 OM 時： batch-find 將 CSV/JSON 寫入 outreachmagic/exports/，然後儲存至 OM。獨立運行： 添加 --skip-om 以在無 OM 的情況下執行（寫入目前工作目錄）。
9. COMPLETE 方塊顯示 IMPORT 和 RELAY（待處理的快照 — 執行 pipeline.py sync；上傳絕非自動）。
10. 積分 — 每找到一封電子郵件花費 1 積分 (trykitt / Icypeas) 或 每驗證一封電子郵件花費 1 積分 (MillionVerifier)。未找到的查詢花費 0 積分。

批次輸入

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

可選地包含 "linkedin_url"（如果有的話）— trykitt 會使用它以獲得更高的匹配率。

指令

# 獨立運行 (無 OM) — 將結果輸出至標準輸出
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

MILLIONVERIFIER_API_KEY 放在本機 .env 檔案中可能會顯示為 ***；OM 的 agent_secrets.env 會透過 ensure_env_loaded() 覆蓋。

若要恢復崩潰的批次，請重新執行相同的 batch-find 指令（會跳過已完成的 API 行）。如果執行因網路/認證錯誤而失敗，請使用 --retry-errors 重新嘗試錯誤行，而不刪除檢查點。

常見工作流程

使用者說	您做
"Find Patrick at stripe.com"	find --name … --domain stripe.com (獨立運行) 或搭配 --save --workspace W (OM)
"Find emails for my CSV" (使用 OM)	batch-find --dry-run → batch-find --yes
"Find emails for my CSV" (獨立運行)	batch-find --skip-om --dry-run → batch-find --skip-om --yes
"Retry failed email lookup"	使用 --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) 的潛在客戶。