email-verification

メールアドレスの検証

送信前にメールアドレスを検証します。email-generation と campaign-sending の間に配置します：

email-generation → email-verification → campaign-sending

環境

プロバイダーの選択と認証情報の確認は、ワークフローのステップ 0 で行います。

入力

入力	必須	ソース
メールアドレス列を含む連絡先 CSV	はい	email-generation の出力、または任意の CSV
シーケンサーのキャンペーン ID	いいえ	campaign-sending から。アップロード済みのリードをクリーニングする場合のみ

ワークフロー

ステップ 0：プロバイダーを確認し、API を把握する

1. 利用するメール検証プロバイダーをユーザーに確認します。
2. プロバイダーの API ドキュメントを取得または参照し、以下を特定します：
   • クレジット確認エンドポイント
   • メールアドレスの単件検証エンドポイント
   • 必須の入力フィールドと認証方式
   • レート制限とリクエストの制約
   • レスポンス形式（status、sub_status）
   • ステータス値と、保持するもの／削除するもの
3. API 認証情報を尋ね、アクセスできることを確認します

ステップ 1：API アクセスとクレジットを確認する

1. プロバイダーのクレジット確認エンドポイントを呼び出します
2. 入力 CSV 内の重複を除いたメールアドレス数を数えます
3. クレジットが重複を除いたメールアドレス数より少ない場合、ユーザーに警告し、一部のみ検証するか中止するかを尋ねます

ステップ 2：メールアドレスを抽出して重複を除く

1. 入力 CSV を読み込み、メールアドレス列を自動検出します（一般的な列名：email、Email、email_address）
2. 重複のないメールアドレスのセットを作成します
3. メールアドレスが空または欠落している行はスキップします
4. 次のように報告します：検証するメールアドレスは {N} 件、メールアドレスのない行を {M} 件スキップしました

ステップ 3：メールアドレスを検証する

重複を除いた各メールアドレスについて、プロバイダーの検証エンドポイントを呼び出します：

• プロバイダーのレート制限（ステップ 0 で確認）を守ります
• メールアドレス 50 件ごとに進捗を表示します
• 結果を {email: {status, sub_status}} として保存します
• エラー（タイムアウト、JSON の解析失敗）が発生した場合は、unknown として記録します

ステップ 4：分類して報告する

プロバイダーのステータス値ごとに結果をグループ化します。ステップ 0 で特定したステータスの対応関係を使い、保持するメールアドレスと削除するメールアドレスを決定します。

一般的な指針（プロバイダーのドキュメントと照合してください）：

処理	一般的なステータス
保持	valid
削除	invalid、do_not_mail、abuse、catch-all、unknown、spamtrap

Catch-all は保持せず、削除します。 Catch-all ドメインは、どのアドレス宛てのメールも受信するため、プロバイダーは特定のメールボックスが存在するか確認できません。これらのアドレスは無視できない割合でバウンスし、バウンスはキャンペーン全体の送信者評価を損ないます。シーケンサーに catch-all アドレスをアップロードしないでください。

ステータスごとの件数をまとめた表を提示し、削除するメールアドレスをそれぞれの status と sub_status とともにすべて一覧表示します。

ステップ 5：クリーニング済み CSV を出力する

1. 元の CSV をフィルタリングし、メールアドレスのステータスが「保持」に該当する行のみ残します
2. クリーニング済み CSV を入力ファイルと同じディレクトリに、{original_name}_verified.csv という名前で書き込みます
3. すべての検証結果を 参照用に {original_name}_verification_results.json に保存します
4. 次のように報告します：{kept} 件のメールアドレスを保持し、{removed} 件を削除しました（catch-all の件数を含むステータス別の内訳も示します）

ステップ 6：シーケンサーから削除する（任意）

ユーザーからシーケンサーのキャンペーン ID が提供された場合：

1. 使用しているシーケンサー（Instantly など）を尋ね、skills/campaign-sending/references/ にある API ドキュメントを参照します
2. 削除対象のメールアドレスごとに、シーケンサーのリード削除エンドポイントを呼び出します
3. レート制限を守ります
4. 次のように報告します：シーケンサーから {N} 件のリードを削除しました

キャンペーンが提供されていない場合は、このステップをスキップし、問題のあるメールアドレスを手動で削除するか、クリーニング済み CSV を再アップロードするようユーザーに伝えます。

出力

ファイル	内容
*_verified.csv	有効なメールアドレスのみを含むクリーニング済み CSV
*_verification_results.json	すべてのメールアドレスの検証結果
コンソールレポート	サマリー表と削除したメールアドレスの一覧

API リファレンス

プロバイダーの API ドキュメントは、ステップ 0 で取得または参照します。事前設定済みのプロバイダードキュメントは同梱されていません。必要に応じて references/ に追加してください。