Email Verifier API クイックスタート

検証を独自の製品やインポート処理に組み込む場合は、API を使用します。verify:read と verify:write のスコープを持つトークンを作成し、秘密として保管して、サインインに使用するものと同じホストを呼び出してください。例では https://YOUR-TREKMAIL-HOST と YOUR_API_TOKEN を置き換えます。

1. トークンを作成する

1. ダッシュボード → AI Agents & API を開きます。
2. トークンを作成します。
3. verify:read と verify:write を有効にします。
4. トークンを安全に保管します。表示されるのは一度だけです。

すべてのリクエストで送信します。

Authorization: Bearer YOUR_API_TOKEN

トークンはシークレットストアまたは環境変数に保管してください。ブラウザー側のコード、公開リポジトリ、サポートチケット、エクスポートした連絡先ファイルには入れないでください。漏えいした疑いがある場合は、トークンを失効させ、ダッシュボードで代わりのトークンを作成します。

2. 単一アドレスを検証する

単一アドレスの結果をすぐに取得するには、POST /api/v1/verify を使用します。mode を省略すると Quick が既定になります。

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

レスポンスには、アドレス、ステータス、信頼スコア、プロバイダー、リスク要因、残りのクレジットなど、安定した最上位フィールドが含まれます。checks オブジェクトには詳細な根拠が記録され、チェックを利用できない場合や Deep モードに追加情報がある場合は内容が変わることがあります。

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

最初に status と trust_score を読み取ります。個々のチェックキーは補足情報として扱い、受信トレイの所有権や配信を保証するものとは考えないでください。

単一 endpoint には、毎分 60 リクエストのルート制限があります。登録時にユーザーが入力したアドレスを確認する場合は、基本的なクライアント側検証の後に呼び出してください。サービスが一時的に利用できないときは、ユーザーを無期限に止めず、わかりやすいエラーを表示します。

3. 一括ジョブを送信する

一括リクエストはファイルアップロードではなく、JSON の emails 配列を受け取ります。ネットワーク再試行で二つ目のジョブが作成されないよう、冪等性キーを含めてください。

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

リストには最大 50,000 件を含められます。TrekMail は重複を正規化し、構文的に無効な項目をジョブから除外します。レスポンスには、ジョブ ID、受理件数、除外された項目の小さなサンプル、請求されたクレジット、Deep の料金内訳が示されます。

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe は Deep の全料金で請求された件数です。skip は、プロバイダーが有用なメールボックスレベルの根拠を提供しないため、通常料金で請求された件数です。レスポンスに示される金額が、その送信に対する正式な費用です。

完全なリストを送信する前に、独自のインポーターでアドレス以外の値を削除してください。API はアドレスを重複排除し、除外件数を報告しますが、ソースを検証すれば、より明確な監査記録が残ります。アプリケーション側でリクエストがタイムアウトした場合は、同じ冪等性キーを使用して同じ一括リクエストを再試行し、新しい送信を作成する前に返されたジョブ ID を確認します。

4. ポーリングしてダウンロードする

ジョブが最終状態になるまで、GET /api/v1/verify/bulk/{jobId} でポーリングします。

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

レスポンスには、status、total、processed、progress、summary、作成時刻、完了時刻が含まれます。完了または一部完了したジョブには、ページ分割された results 配列が含まれます。

適切な間隔を空け、待機時間を延ばしながらポーリングしてください。ジョブは処理開始前に保留状態が続くことがあり、受信側プロバイダーが追加の根拠を提供する場合、Deep の処理にはさらに時間がかかることがあります。リストの大きさだけから固定の完了時間を想定しないでください。

結果が利用可能になったら、小さい結果ページを要求したり、既知のアドレスを検索したりできます。

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

処理済みのジョブを CSV としてダウンロードします。

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API のエクスポートフィルターは all、safe、safe_risky（Safe + Valid + Risky）です。

保留中または実行中のジョブを停止するには、キャンセル endpoint を使用します。未処理分のクレジットが返却され、処理済みの行は保持されます。

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Verifier のジョブ記録と結果の両方を削除するときだけ、ジョブを削除してください。まだ実行中の場合はまずキャンセルし、その後、冪等性キーを使用して削除 endpoint を呼び出します。完全なリファレンスには両方の呼び出しが掲載されています。

5. 一般的なレスポンスに対応する

• 402: アカウントにクレジットを追加する必要があります。
• 422: リクエスト本文、選択したモード、または一括リクエストに必要な冪等性キーを確認してください。
• 429: リクエスト頻度を下げ、待機時間を延ばして再試行してください。
• 503: 検証は一時的に利用できません。後で再試行してください。失敗した単一アドレス検証のクレジットは返却されます。

本番連携のチェックリスト

1. トークンをサーバー側に保管し、必要な二つの Verifier スコープだけを付与します。
2. 一括 API を呼び出す前に、連絡先入力を検証して正規化します。
3. ジョブ ID、送信したリストの識別子、冪等性キー、返された credits_charged の値を保存します。
4. 短いループではなく、待機時間を延ばしながらポーリングします。
5. 15 日間の保持期間が終了する前に CSV を保存または処理します。
6. 同意、オプトアウト、抑制に関する判断は独自のアプリケーションで管理します。Verifier の結果はそれらに代わるものではありません。

すべての endpoints、スコープ、レスポンスフィールドについては、Email Verifier REST API リファレンスを参照してください。