一括メール検証API：バッチジョブの実践的なワークフロー

一括メール検証API：バッチジョブの実践的なワークフロー

質問：自社システムに大量のアドレスリストがあります。FairValid APIにバッチで送信し、エラーを安全に処理し、クレジットの状況を見失わずに結果を読み戻すにはどうすればよいでしょうか？

簡単な回答：まずテストキーを使ってサンドボックスで始めます。次にリストを最大5,000件のアドレスごとのジョブに分割し、各ジョブに固有の冪等キーを付与します。各ジョブをライブキーで送信し、ステータスを確認して、結果を判定別にページングで取得します。保留中のチェック、技術的な失敗、「不明」の結果は、それぞれ別の三つの状況として扱ってください。

2026年11月13日に、FairValidのAPIリファレンス、結果ガイド、クレジットルールと照らし合わせて根拠を確認しました。

ステップ1：まずサンドボックスで構築する

APIリファレンスによると、APIキーの画面でテストキーを作成し、サーバー上で保管し、ベースURLとともに環境に設定します。テストキーはexample.comドメインの予約済みアドレスで機能します。プロバイダーへの呼び出しは行われず、クレジットも使用しません。テストキーは専用のシミュレーションジョブにアクセスします。

テストジョブは決定的な状態を返します：completed、pending、failed、cancelledのいずれかです。正確なサンドボックス用アドレスはAPIリファレンスで確認し、それを使ってコードがこれらの状態を処理できることを確かめてください。これらのケースが示すのは、想定された結果のみです。統合のすべての分岐を網羅するものではないため、独自のエラー処理経路は別途確認してください。

ステップ2：適切なスコープを持つライブキーに移行する

APIリファレンスによると、本番環境でジョブを作成するにはsubmitスコープを持つライブキーが必要です。ジョブの状態と結果を読み取るにはreadスコープを追加します。ライブキーにはbalanceスコープも付与できます。キーのシークレット全体は一度しか表示されないため、作成時にサーバー上で安全に保管してください。失効したキーでは新しいリクエストは受け付けられません。

ライブジョブはワークスペースの検証キューとクレジット残高を使用します。キーのスコープ、キーの上限、ワークスペースのアクセス権、処理制限は引き続き適用されます。ライブキーで無制限にアクセスできるわけではありません。

ステップ3：リストを分割してジョブを送信する

各ジョブでは、JSON形式で1～5,000件のアドレスを最大2 MiBまで受け付けます。実践的な方法の一例を紹介します：

1. リストを分割します。例えば、12,000件のアドレスは5,000件、5,000件、2,000件の三つのジョブになります。
2. 各チャンクに固有の固定Idempotency-Keyを付与し、どの行がどのチャンクに入ったかを記録します。この対応関係を自社側で保持しておくと、結果を自社のレコードに結び付けやすくなります。
3. ジョブエンドポイントに送信します。新しいジョブではHTTP 202とUUID形式のjob_idが返されます。一致する再試行ではHTTP 200と同じジョブが返されます。つまり、タイムアウト後に同じキーで同じリクエストを再送すれば、既存のジョブを取得できます。

ステップ4：似ている二つのエラーに対処する

以下のどちらのレスポンスも送信を妨げる可能性がありますが、意味は異なります：

• HTTP 503 live_verification_unavailableは、運用上の一時停止中に返されることがあります。APIリファレンスによると、この場合クレジットは確保されません。後で同じIdempotency-Keyを使って再試行してください。
• HTTP 402 key_cap_reachedは、新しいリクエストがキーの累計利用上限を超えることを意味します。この上限には、すでに課金されたクレジットと、受け付けられた一意の識別子のために確保されたクレジットが含まれます。ジョブも確保も作成されません。累計上限は時間の経過で回復しないため、待っても解決しません。APIキー設定でキーの上限を見直すか、作業に十分な残り上限があるキーを使用してください。また、キーの上限によってワークスペースにクレジットが追加されることはありません。あくまでそのキーが使用できる量を制限するだけです。

適切な担当者に適切なアラートが届くよう、これら二つのレスポンスは権限エラーや処理制限とは別に記録してください。

ステップ5：ジョブの状態を追跡し、結果をページングで取得する

ジョブエンドポイントは、ジョブの現在の状態と概要を返します。ジョブのステータスはqueued、running、paused、canceling、canceled、completedのいずれかです。キャンセルを要求しても、すでに処理中の作業は完了する場合があります。

結果エンドポイントは、一度に最大50件の結果を署名付きのnext_cursorとともに返します。この値をcursorクエリパラメーターとして渡してください。元のフィルターと検索条件が引き継がれます。フィルターはall、valid、invalid、catch_all、unknown、still_checking、not_checkedです。これらを使えば、unknownとされたものすべてなど、判断が必要な行だけを取得できます。

ステップ6：結果を判断につなげる

結果ガイドでは、結果は配信の保証ではなく根拠であると説明しています：

• 有効は、利用可能な肯定的チェック結果を示します。受信トレイへの配信を保証するものではありません。
• 無効は、アドレスがチェックに通らなかったことを意味します。
• キャッチオールは、ドメインが多くのアドレスを受け入れる可能性があるため、特定のメールボックスに関する結論の確実性が低い場合があることを意味します。アドレスを使用する前に詳細を確認してください。
• 不明は、チェックで信頼できる回答が得られなかったことを意味します。
• 確認中は、まだ最終的な回答が出ていないことを意味します。ポーリングを続け、「不明」として扱わないでください。

技術的な失敗と未処理の項目は別のカテゴリーです。FairValidのクレジットルールでは、これらが「不明」に置き換えられることはないとしています。

ステップ7：クレジットの確保を理解する

APIリファレンスによると、ワークスペースのクレジットはチェックが処理に受け付けられた時点で確保されます。結果にはダッシュボードと同じ課金および返却ルールが適用されます。クレジットルールでは、完了した「有効」または「無効」の結果ごとにクレジットが一つ消費されます。「不明」および未解決の「キャッチオール」の結果は、確保されたクレジットが解放または返却されるため、最終的に検証クレジットは差し引かれません。保留中は最終結果ではありません。技術的な失敗と未処理の作業も、最終的にクレジットは差し引かれません。返却されたクレジットは、元のロットと有効期限のルールをそのまま保持します。

残高エンドポイントは、ライブワークスペースの利用可能なクレジットと確保中のクレジットを報告します。free_allowance_heldフィールドがtrueの場合、無料枠は保留中で、available_creditsやfree_availableには含まれません。有料クレジットは引き続き利用できます。元のアカウントには毎月登録日に300無料クレジットが付与され、未使用の無料クレジットは翌月に繰り越されません。追加のワークスペースに別途無料枠は付与されません。無料クレジットが先に使用され、有料クレジットはアカウントが有効な間は失効しません。

簡単なチェックリスト

• テストキーと文書化されたサンドボックスのケースでテストする。
• submitとreadのスコープを持ち、予定する作業に見合った上限が設定されたライブキーを使用する。
• 各チャンクを5,000件以下のアドレスに抑え、チャンクごとに固定の冪等キーを付与する。
• 503は後で同じキーで再試行する。402は待っても解決しないため、上限に対処する。
• 署名付きカーソルを使い、判定でフィルターして結果をページングで取得する。
• データ上で、保留中、技術的な失敗、「不明」を区別して保持する。

このワークフローを試したい場合は、初めてライブで送信する前に、テストキーを作成してクレジットを使わずにサンドボックスジョブを実行できます。エンドポイントの詳細はAPIリファレンスをご覧ください。