Email Finder（メールアドレス検索）は何をしますか？

氏名 + 企業ドメインから仕事用メールアドレスを検索します。trykittを優先、見つからなければIcypeasを使用します。

単体でも動作します。 APIキーだけが必要です。Outreach Magicと組み合わせると、クレジット節約の重複排除、永続ストレージ、セッションを越えた利用が可能になります。

セットアップ

単体（Outreach Magicなし）

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` は任意）

エージェントルール

OM使用時： 検索前に確認（check / find + --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 を実行してスキップ件数を確認（CSVの email が空でもOMに既にメールがあるリードをスキップ）。
batch-find は各API呼び出し直前にOMを再確認（バッチ開始後に解決されたリードをスキップ）。
OM使用時： batch-find は outreachmagic/exports/ 以下にCSV/JSONを書き出し、その後OMに保存。単体： --skip-om を追加するとOMなしで実行（カレントディレクトリに書き出し）。
COMPLETEボックスには IMPORT と RELAY が表示されます（保留中のスナップショット — pipeline.py sync を実行。アップロードが自動で行われることはありません）。
クレジット — 見つかったメール1件につき1クレジット（trykitt / Icypeas）、または 検証されたメール1件につき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

ローカルの .env にある MILLIONVERIFIER_API_KEY は *** と表示されることがあります。OMの agent_secrets.env が ensure_env_loaded() によって上書きされます。

クラッシュしたバッチを再開するには、同じ batch-find コマンドを再実行します（完了したAPI行はスキップされます）。ネットワークエラーや認証エラーで実行が失敗した場合は、--retry-errors を使用してエラー行を再試行します（チェックポイントは削除せず）。

よくあるワークフロー

ユーザーの依頼	エージェントの対応
"stripe.com の Patrick のメールを探して"	`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`
"失敗したメール検索を再試行"	同じ `batch-find` コマンド + `--retry-errors`

トラブルシューティング

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（メールアドレス検索）