メール検証APIワークフロー：FairValidでサンドボックスから本番環境へ

メール検証APIワークフロー：サンドボックスでのテストから本番環境の結果まで

質問：自社システムにメール検証を組み込む開発者です。最初のテスト呼び出しから信頼できる本番環境の結果に至るまで、どのような手順を踏めばよいですか？

簡単な回答：まずTestキーと無料サンドボックスから始めます。次に、必要なスコープだけを持つLiveキーに切り替えます。すべての送信に冪等キーを付けます。ジョブの状態を読み取り、結果をページ送りで取得します。各結果と各エラーコードはそれぞれ個別に処理します。以下の手順はFairValidの顧客向けAPIリファレンスに沿っています。

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

APIキーのページでTestキーを作成し、サーバー上で保管します。リファレンスではFAIRVALID_API_KEYとFAIRVALID_BASE_URLの二つの環境変数を使用しています。Testキーはプロバイダーへの呼び出しを行わず、クレジットも消費しません。

Testキーは、example.comドメイン上の少数の予約済みアドレスのみを受け付けます。これらのアドレスは、有効、無効、キャッチオール、不明、保留中、利用不可の各結果をシミュレートします。正確なアドレスはAPIリファレンスの「無料サンドボックス」セクションに記載されています。テストジョブは、完了、保留中、失敗、キャンセル済みのいずれかの固定された再現可能な状態を返します。一括テストジョブは、ステータス、結果、キャンセルに対応しています。

サンドボックスで確認できるのは、これらの特定の結果です。統合が通りうるすべての経路を網羅しているわけではないため、ステップ7で説明するエラーコードについては別途処理を計画してください。

一括テストジョブは、ワークスペースごとに毎時新規20件、または30日あたり100件に制限されています。いずれかの上限を超えるとHTTP 429が返されます。同一内容の再試行では、引き続き元のジョブが返されます。

ステップ2：必要なスコープを持つLiveキーに移行する

本番環境では、submitスコープを持つLiveキーを作成します。バッチにはPOST /api/v1/jobsを、単一アドレスにはPOST /api/v1/verificationsを使用します。キーでジョブの状態や結果も読み取る必要がある場合は、readスコープを追加します。Liveキーにはbalanceスコープを付与することもできます。これとは別に、GET /api/v1/balanceはワークスペースの利用可能なクレジットと保留中のクレジットを読み取ります。シークレット全体は一度しか表示されないため、キーの作成時に安全に保管してください。

Liveジョブは、ワークスペースの検証キューとクレジット残高を使用します。キーのスコープ、キーの上限、ワークスペースのアクセス権、処理の制限はすべて引き続き適用されます。

ステップ3：冪等キーを付けてジョブを送信する

各ジョブでは、JSON形式で1～5,000件のアドレスを、最大2 MiBまで受け付けます。すべてのジョブ送信と、すべての単一アドレスのLive送信にIdempotency-Keyヘッダーを付けてください。キーは8～128文字で、英字、数字、ドット、コロン、アンダースコア、ハイフンを使用できます。

• 新規ジョブでは、UUIDのjob_idとともにHTTP 202が返されます。
• 一致する再試行では、同じジョブとともにHTTP 200が返されます。
• 本文を変更して冪等キーを再利用すると、HTTP 409 idempotency_conflictが返されます。

リクエストが処理されたかどうか判断できない場合は、同じAPIキー、同じ冪等キー、同じ正規化済みの本文で再試行してください。リプレイはAPIキー単位で適用されるため、その認証情報を差し替えて再送信すると、二回目の実行が作成される可能性があります。新しい冪等キーは、課金される可能性のある新規実行を本当に行いたい場合にのみ使用してください。

ステップ4：ジョブを読み取り、結果をページ送りで取得する

GET /api/v1/jobs/{id}でジョブを読み取ります。ステータスは、キュー待ち、実行中、一時停止、キャンセル処理中、キャンセル済み、完了のいずれかです。結果はGET /api/v1/jobs/{id}/resultsで読み取ります。各ページは最大50件の結果と、署名付きのnext_cursorを返します。その値をcursorクエリパラメーターとして渡してください。元のフィルターと検索条件が保持されます。

フィルターは、all、valid、invalid、catch_all、unknown、still_checking、not_checkedです。ジョブを停止するにはPOST /api/v1/jobs/{id}/cancelでキャンセルを要求しますが、すでに進行中の処理は完了する場合があります。

リファレンスでは、署名付きの完了イベントについても説明しており、Webhook管理へのリンクも掲載されています。

ステップ5：各結果をそれぞれ独立した状態として扱う

結果ガイドでは、各結果の意味を説明しています：

• 有効：利用可能な肯定的な検証結果です。受信トレイへの配信を保証するものではありません。
• 無効：アドレスは検証を通過しませんでした。
• キャッチオール：ドメインが多数のアドレスを受け付ける可能性があるため、メールボックス単位の結論は確実性が低い場合があります。利用する前に詳細を確認してください。
• 不明：検証で信頼できる回答を返せませんでした。
• 確認中：まだ最終的な回答は出ていません。

ガイドでは技術的な失敗と未処理の項目を「不明」とは別に説明しており、APIでもunknown、still_checking、not_checkedを別々のフィルターとして提供しています。自社のデータでは、これらの状態を「不明」にまとめず、別々のフィールドまたはステータスとして保持してください。

ステップ6：照合の前にクレジットの保留を理解する

APIリファレンスによると、ワークスペースのクレジットは、検証が処理対象として受け付けられた時点で予約されます。その後の結果には、ダッシュボードと同じ課金および返還のルールが適用されます。FairValidの料金ページによると、クレジットの保留は実行中の検証のための枠を確保するもので、課金は最終結果によって決まります：

• 有効または無効：完了した結果ごとに1クレジット。
• 不明またはキャッチオール：最終的に検証クレジットは差し引かれません。保留されたクレジットは解放または返還されます。
• 確認中：まだ最終的な課金はありません。保留は確定した課金ではありません。
• 技術的な失敗と未処理の作業：最終的に検証クレジットは差し引かれません。予約は解放または返還されます。

ジョブの途中で残高を確認する場合、保留中のクレジットはまだ最終的な課金ではないことに注意してください。照合は結果が確定してから行いましょう。すべてのアカウントには毎月300の無料クレジットが含まれます。無料クレジットは優先的に使用され、翌月に繰り越されません。有料クレジットは、アカウントを閉鎖しない限り、未使用分が翌期以降も引き続き利用できます。

ステップ7：単一の再試行ルールではなく、原因別にエラーを処理する

• 401：キーがない、失効している、または必要なスコープがありません。認証情報またはそのスコープを修正してください。
• 402 key_cap_reached：新しいリクエストがキーの累計上限を超えるため、ジョブも保留も作成されませんでした。上限には、すでに課金されたクレジットと、受け付けられた一意のIDのために予約されたクレジットが計上されます。累計の上限であるため、時間の経過で回復することはなく、待っても解消されません。アクセス権を持つ担当者に、そのキーの上限設定を見直してもらってください。上限設定でワークスペースにクレジットを追加することはできません。
• 422：無効なアドレス、またはリストの制限です。入力内容を修正してください。
• 503 live_verification_unavailable：運用上の一時停止中は、新しいLive送信に対してクレジットを保留せずにこのエラーが返されることがあります。後で同じ冪等キーを使って再試行してください。送信結果が不確かな状況での503は、ジョブが作成されなかったことを証明するものではないため、元のキーを再利用してください。

すべてのエラーには、コード、メッセージ、リクエストIDが含まれます。サポートに問い合わせる際に備えて、三つすべてをログに記録してください。

推奨される作業の順序

1. サンドボックスで統合を構築し、シミュレートした各結果が想定どおりに処理されることを確認します。
2. 上記のエラーコードに対する明示的な処理を追加します。
3. 必要最小限のスコープと、予算に合った上限を設定したLiveキーを作成します。
4. まずは小規模なLiveジョブから始めます。その結果とクレジットの状態をダッシュボードと照らし合わせてから、規模を拡大します。

このワークフローを試してみたい場合は、無料サンドボックスでクレジットを一切消費せずにシミュレートされた結果をテストできます。正確なリクエストの詳細はAPIリファレンスに記載されています。