Email Verifier REST APIリファレンス

Email Verifier APIは/api/v1で提供されます。アカウントへのサインインに使用するTrekMailホストを指定してください。以下ではhttps://YOUR-TREKMAIL-HOSTをプレースホルダーとして使用します。

認証とスコープ

APIトークンをAuthorizationヘッダーで渡します。

Authorization: Bearer YOUR_API_TOKEN

トークン作成時にスコープを有効にします。

クライアントがジョブを送信し、その結果を読み取るかダウンロードする場合は、両方のスコープを付与します。

ホストとリクエスト形式

すべての例でJSONリクエスト本文とBearerトークンを使用します。ダッシュボードのファイルアップロードはAPIとは別です。POST /verify/bulkはmultipartファイルではなくJSONのemails配列を受け取ります。アカウントとトークンに属する正確なホストを使用してください。別のブランドホストでトークンや残高が使えるとは限りません。

POST /verifyとPOST /verify/bulkにはContent-Type: application/jsonを送信します。トークンと冪等性値はクライアント側コードの外部に保存してください。

冪等性

POST /api/v1/verify/bulkとDELETE /api/v1/verify/bulk/{jobId}にはIdempotency-Keyヘッダーが必要です。意図した操作ごとに新しい値を生成し、同じ操作を再試行するときだけ再利用します。

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

単一検証とジョブのキャンセルにはこのヘッダーは不要です。同じ正規化済みリストとモードを24時間以内に一括送信した場合も重複検出で保護されますが、再試行には冪等性キーを使用してください。

ネットワーク結果が不明な場合

一括リクエストの応答を受信できなかった場合、新しいキーで別のリストを送信しないでください。同じキーで同一のリクエストを再送します。TrekMailがジョブIDを返すまで、キーを元リストの識別子とともに保存してください。これにより不要な二重課金を防げます。

エンドポイント一覧

表の各パスの先頭に/api/v1を付けます。

クレジット残高の取得

GET /api/v1/verify/credits

標準TrekMailホストでは、プラン枠と購入残高が返されます。

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

White Labelホストでは購入クレジットだけがブランド製品で利用できるため、応答にはpurchased_balanceとtotal_availableが含まれます。

リクエスト例:

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

大規模な送信の直前に残高を取得してください。残高はスナップショットです。複数ジョブを送信するアプリは、古い残高から後で計算せず、各一括応答の課金額を記録します。

残高フィールド

White Labelは購入クレジットのみを使うため、残高応答のフィールドは意図的に少なくなります。

1件のアドレスを検証

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

応答にはemail、status、trust_score、checks、provider、risk_factors、credits_remainingが含まれます。標準ホストのcredits_remainingにはmonthlyとpurchasedがあります。checksの詳細はモードや受信側プロバイダーが提供する情報により変わります。

Quickは1クレジット、Deepは通常2クレジットです。プロバイダー固有の例外は1クレジットで計算されます。課金後に検証を実行できない場合、単一リクエストは課金を返金し、一時的利用不可を返します。

リクエスト例:

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"}'

通常のアプリ契約としてトップレベルのstatus、trust_score、provider、risk_factorsを使用します。checksは補足情報ですが、上流の検査が省略、利用不可、またはDeepで追加情報を得た場合にキーが変わることがあります。

単一結果の解釈

受け入れられたリモート応答を所有権や許可の確認として扱わないでください。購読、オプトアウト、連絡先設定の判断は別に管理します。

一括ジョブの作成

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

重複は料金計算前に正規化されます。新しいジョブが成功すると201を返します。

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

probeとskipはDeep料金の計算を示します。deep_savingsは全アドレスを完全なDeep料金にした場合との差です。重複リストでは別のジョブを開始せず、既存のjob_idとステータスを返します。

リクエスト例:

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

APIはジョブ受付前にメール構文を検査します。すべてが拒否されると422を返し、ジョブを作りません。一部が拒否された場合はrejected_countとrejected_sampleに最大5件を返します。この少数例を完全なクリーニング報告として使わず、インポーター側の検証結果を保持してください。

一括送信チェックリスト

1. アプリでソースを読み取り、正規化します。
2. リクエストを50,000件以下にします。
3. リクエスト前に冪等性キーを生成して保存します。
4. 担当者が後で識別できるジョブ名を付けます。
5. TrekMailが返すjob_id、credits_charged、料金内訳を保存します。
6. 保存したjob_idをポーリングし、元のHTTPリクエストから完了を推測しません。

ジョブの取得

GET /api/v1/verify/bulk/{jobId}

基本応答にはjob_id、name、status、total、processed、progress、summary、created_at、completed_atが含まれます。

完了、一部完了、失敗したジョブで結果がある場合は、次も含まれます。

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

任意のクエリパラメーター:

処理済み行があるキャンセル済みジョブはダウンロードできます。エクスポートにはダウンロードエンドポイントを使用します。

推測せずにジョブ状態を読む

APIクライアントはバックオフ付きでポーリングしてください。既存ジョブがまだ待機中、またはローカルでタイムアウトしたという理由だけで、新しい一括送信を行わないでください。

ステータス応答例

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

処理の進行に伴いsummaryは増加します。アプリが現在認識するカテゴリだけを合計せず、processedとtotalで進捗を表示します。

ジョブのダウンロード

GET /api/v1/verify/bulk/{jobId}/download

処理済み行がある完了、一部完了、キャンセル済みジョブをダウンロードできます。Email、Status、Trust Score、Provider、Risk Factors列のCSVがストリーミングされます。

例:

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

15日間の結果保持期間内に保存してください。CSVは独自ワークフロー用であり、別システムの同意、購読、連絡先レコードを変更しません。

処理済みエクスポートがない間、ダウンロードは競合を返します。先に状態を確認してください。成功時はJSONラッパーではなくCSVをストリーミングするため、HTTPクライアントでファイル応答として扱います。

ジョブ一覧

GET /api/v1/verify/bulk

page、per_page、任意のstatusを使用します。per_pageの既定値は20で、1から100を指定できます。状態はpending、processing、completed、partial、cancelled、failedです。

応答にはjobs配列とpaginationオブジェクトが含まれます。各レコードにはID、名前、状態、合計、処理済み件数、進捗、日時があります。

例:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

ワーカーの再起動時やジョブIDの照合には一覧エンドポイントを使います。ジョブ名を一意の識別子とせず、返された数値のjob_idを保存してください。

ジョブ一覧の応答形式

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

運用画面で実行中または完了済みだけが必要な場合はstatusを使います。多数のリストを検証するアカウントではページネーションが重要です。1回の応答に全履歴があると想定しないでください。

ジョブのキャンセル

POST /api/v1/verify/bulk/{jobId}/cancel

待機中または実行中のジョブだけをキャンセルします。成功時の応答:

{"status":"cancelled","credits_refunded":40}

未処理分が返金されます。キャンセル到達前に終了状態になった場合、APIは結果を変更せず競合を返します。

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

キャンセルしてもジョブは削除されません。必要なら処理済み行をダウンロードし、その後完了レコードを削除します。

ジョブの削除

DELETE /api/v1/verify/bulk/{jobId}

実行中のジョブは先にキャンセルします。TrekMailが準備済みソースリストを安全に消去した後、ジョブと結果が完全に削除されます。成功時の応答:

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

Verifierレコードに対して永続的な操作です。アプリがダウンロード済みのCSVは撤回されないため、そのコピーには独自の保持処理を適用してください。

削除順序

1. ジョブ状態を取得します。
2. 待機中または処理中ならキャンセルします。
3. 保持が必要な処理済みエクスポートを保存します。
4. 実行中でないジョブを冪等性キーで削除します。
5. 独自システムのコピーをプライバシーと保持規則に従って削除します。

エラーと再試行

単一検証のルート制限は毎分60件、一括送信は毎分10件です。バックオフを実装し、一括再試行では同じキーを維持し、不明なネットワーク結果の後に盲目的に再送しないでください。

安全な再試行パターン

1. 一括送信前に1つの冪等性キーを生成して保存します。
2. そのキーでリクエストを送信します。
3. 応答を失ったら、同じキーで同一リクエストを再試行します。
4. 返されたjob_idを保存し、そのソースリストの新規送信を停止します。
5. 終了状態までポーリングし、結果をダウンロードまたは処理します。

単一検証の一時的な503はサービスが検査を完了できなかったことを示します。通常のバックオフで後で再試行し、データベースでInvalidに変換しないでください。

連絡先データの保護

メールリストは多くの場合に個人データです。検証に必要なデータだけを送り、トークンをジョブ実行システムに限定し、完全なアドレス配列をログに残さないでください。必要な場合は完全なリストではなく、ジョブID、件数、時刻、概要結果を記録します。

TrekMailは結果を15日間保持します。大量リストの統合前に、安全なエクスポート保存または削除経路を用意してください。

検証シグナルは所有権、同意、将来の配信を証明しません。Safeのアドレスでも、許可と抑制をアプリで管理してください。