開発者向け

メール検証API。

フォームには単一アドレスのチェックを、顧客リストには非同期タスクをご利用ください。現在のメールプロバイダーはそのまま使えます。

まずは1件のアドレスから

最初のリクエスト。

キー不要の無料デモエンドポイントをご利用ください。レート制限があり、サービスのお試し用です。

curl -X POST https://api.zbounce.net/v1/demo \
  -H 'Content-Type: application/json' \
  -d '{"email":"hello@example.com"}'

有料のチェックには、パッケージを購入し、 /v1/fast-verify を使用します。キーは X-API-Keyで送信してください。キーをURL、ソース管理、アナリティクスに含めないでください。

curl -X POST https://api.zbounce.net/v1/fast-verify \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"email":"hello@example.com"}'

Pythonの例

import os, requests

response = requests.post(
    "https://api.zbounce.net/v1/fast-verify",
    headers={"X-API-Key": os.environ["ZBOUNCE_API_KEY"]},
    json={"email": "hello@example.com"},
    timeout=35,
)
response.raise_for_status()
print(response.json())

Node.jsの例

const response = await fetch("https://api.zbounce.net/v1/fast-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.ZBOUNCE_API_KEY,
  },
  body: JSON.stringify({ email: "hello@example.com" }),
  signal: AbortSignal.timeout(35000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

リストを送れば、結果が返ります

大きなリストを検証。

POST /v1/tasks

1タスクあたり最大10,000件のアドレスを送信できます。返されたタスクIDを保存し、 accepted, skipped および invalidsを確認してください。すべての入力がキューに入るとは限りません。重複、形式不正、配信停止済みのアドレスは除外されることがあり、残高が少ない場合は一部のみ受け付けられることがあります。

curl -X POST https://api.zbounce.net/v1/tasks \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $ZBOUNCE_API_KEY" \
  -d '{"emails":["hello@example.com","contact@example.org"]}'

ステータスをポーリングしてから、各結果ページを取得してください。無効な入力のみを含むレスポンスでは、タスクIDが空になることがあります。その場合はポーリングしないでください。

curl "https://api.zbounce.net/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

curl "https://api.zbounce.net/v1/tasks-results/$TASK_ID?page=1&per_page=100" \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

完了したタスクの結果はJSON形式です。受け付けられたリスト全体を取得するまで、ページの取得を続けてください。完了を自動で通知するには、 mode: "completed" を指定したWebhookをタスク作成時に渡してください。

{
  "emails": ["hello@example.com"],
  "webhook": {
    "url": "https://your-app.example/hooks/verification",
    "mode": "completed",
    "secret": "YOUR_PRIVATE_WEBHOOK_SECRET"
  }
}

本番環境で有効にする前に、スキーマでWebhookの設定と署名の検証方法を確認してください。

レスポンスを理解する

形式が正しくても、存在するとは限りません。

これらは別々のシグナルです。形式が正しいアドレスでも、存在しない、使い捨てである、または確認できない場合があります。

フィールド	意味
`valid`	アドレスが構文検証を通過しました。これだけではメールボックスの存在は確認されません。
`exists`	メールボックス確認の結果です。エラーやキャッチオールのシグナルと合わせて解釈してください。
`disposable`	ドメインが一時的なメールプロバイダーとして認識されました。
`accept_all`	サーバーが任意のアドレスを受け入れるため、特定のメールボックスを確実に確認できません。
`error_category`	no_mx、risky、一時的なサーバーの問題など、失敗やリスクの理由を示します。
`permanent_error`	チェック中に恒久的な失敗が返されました。一時的な失敗を恒久的な拒否として扱わないでください。
`ttl`	返された場合、再試行やキャッシュのタイミングの目安（秒）を示します。

検証によって、配信を保証したり、苦情をなくしたり、メールボックスの所有を証明したりすることはできません。

残高を把握する。

GET /v1/me

curl https://api.zbounce.net/v1/me \
  -H "X-API-Key: $ZBOUNCE_API_KEY"

レスポンスには、残りのクレジット、予約済みのクレジット、使用済みのクレジット、キーの種類、有効期限が含まれます。通常の検証では1クレジットを使用しますが、実際のフィルタリングと課金は、ルートとタスクの受け付け状況によって異なります。アップロードしたリスト全体を処理済みとみなす前に、レスポンスを確認してください。

429レスポンスは、リクエストが制限されていることを意味します。間隔を空けてから再試行してください。現在のAPIでは、その他のエラーがJSONまたはテキストで返されることがあります。HTTPエラーを検証結果として解釈しないでください。

検証APIの仕様。

OpenAPI JSONをダウンロード

公開仕様には、デモ、高速検証、タスク、タスクのステータス、結果、アカウント残高が含まれます。配信および管理用のエンドポイントは、この検証リファレンスの対象外です。

プラットフォームとの接続でお困りですか？ support@zbounce.net