メールアドレス検証APIのドキュメント
メールアドレスの検証、一括チェック、キャッチオールドメインやSEGの背後にあるアドレスの詳細チェックを行えます。すべてのエンドポイントはJSONを使い、APIキーで認証します。料金がかかるのは成功したチェックだけです。
はじめに
Giggal.aiのAPIでは、メールアドレスの検証、1ジョブあたり最大50,000件の一括チェック、キャッチオールドメインやSEGの背後にあるアドレスの詳細チェックを行えます。JSONを使うシンプルなREST APIです。成功したチェックごとに、アカウントのクレジットを使います。
https://api.giggal.ai/v1APIキーはGiggal.aiのダッシュボードで作成します。サイドバーのDeveloper APIタブを開き、Create API Keyをクリックしてください。各キーはアカウントにひも付き、使用量をキーごとに記録します。キーはいつでも無効にできます。
Developer APIタブを開くすべてのレスポンスは同じJSON構造です。
// Success
{ "success": true, "data": { ... }, "meta": { ... } }
// Error
{ "success": false, "error": "Human-readable error message" }curl -X POST https://api.giggal.ai/v1/verify \
-H "Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email":"info@giggal.ai"}'認証
すべてのリクエストで、次のどちらかのヘッダーにAPIキーを入れて送ってください。どちらでも動作します。
Authorization: Bearer tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxX-API-Key: tp_live_xxxxxxxxxxxxxxxxxxxxxxxxxキーがない、無効、または無効化されている場合は、HTTP 401エラーになります。APIキーをクライアント側のコードに置かないでください。API呼び出しはご自身のバックエンドから送ってください。
POST /v1/verify-batchとPOST /v1/catchallでは、Idempotency-Keyヘッダーを送ってください。同じキーで再試行すると、最初のレスポンスが返ります。ジョブが重複せず、クレジットが二重に差し引かれることもありません。
Idempotency-Key: 2026-07-24-list-batch-421件ずつのチェック
このグループには1個のエンドポイントがあります。
/v1/verifyメールアドレスを1件チェックする
メールアドレスを1件、同期的にチェックします。1クレジットを使います。ドメインがキャッチオールドメインの場合は、同じリクエストの中で詳細チェックを行い、レスポンスにcatch_all_scoreとcatch_all_verdictが入ります。
一括チェック
このグループには3個のエンドポイントがあります。
/v1/verify-batch一括チェックを開始する
1ジョブあたり最大50,000件のメールアドレスを送れます。処理は非同期です。進行状況はGET /v1/jobs/:jobIdで確認してください。Idempotency-Keyヘッダーを送ると、二重課金なしでジョブの作成を再試行できます。
/v1/jobs/:jobId一括チェックのジョブの状況を確認する
進行状況を確認するときに呼び出します。ステータスはprocessingからcompleted（またはfailed）に変わります。推奨する間隔は10〜15秒ごとです。小さなリスト（メールアドレス50件未満）は、通常30秒以内に終わります。
/v1/jobs/:jobId/results一括チェックのジョブの結果を取得する
ステータスがcompletedになったら、メールアドレスごとの結果を取得します。結果はページに分かれています。クエリパラメーターのpageとlimitを指定してください。結果は48時間保存されます（ジョブのresultsExpiresAtを参照）。
キャッチオールドメインのチェック
このグループには4個のエンドポイントがあります。
/v1/catchallキャッチオールドメインのチェックを開始する
完了した一括チェックのジョブに対して、キャッチオールドメインの詳細チェックを実行します。元のジョブでキャッチオールドメインと判定されたアドレスだけを再チェックします。1件あたり1クレジットを使います（レスポンスのcreditsRequiredを参照）。
/v1/catchall/:taskIdキャッチオールドメインのタスクの状況を確認する
進行状況とverdictCountsの最新の件数を確認するときに呼び出します。キャッチオールドメインのタスクは、アドレスの件数に応じて、通常数秒から数分で終わります。
/v1/catchall/:taskId/resultsキャッチオールドメインのタスクの結果を取得する
メールアドレスごとの結果を、ページに分けて取得します。スコアの内訳（ドメインからのシグナルとドメインの経過年数）も含まれます。
/v1/catchall/:taskId/downloadキャッチオールドメインの結果をCSVでダウンロードする
完了したキャッチオールドメインのタスクの全結果を、Email、Score、Verdictの列を持つCSVファイルでダウンロードします。Content-Typeはtext/csvです。
アカウント
このグループには1個のエンドポイントがあります。
/v1/creditsクレジット残高を確認する
アカウントの残高を表示します。使えるクレジット、予約済みのクレジット（実行中のジョブのために確保した分）、アカウント開設からの合計です。結果がunknownのチェックのクレジットは自動で返却され、ここにも記録されます。
エラーと制限
| ステータス | 意味 |
|---|---|
| 200 OK | リクエストが成功しました（同期チェック、またはステータスや結果の取得）。 |
| 202 Accepted | 非同期のジョブまたはタスクが作成され、キューに入りました。 |
| 400 Bad Request | パラメーターがない、または無効です（メールアドレスの形式が正しくない、emailsのリストが空、jobIdがない）。 |
| 401 Unauthorized | APIキーがない、無効、または無効化されています。 |
| 402 Payment Required | この操作に必要なクレジットが足りません。 |
| 404 Not Found | このジョブIDまたはタスクIDは、お使いのアカウントに存在しません。 |
| 409 Conflict | ジョブが必要な状態になっていません（例：ジョブの完了前に結果を要求した）。 |
| 410 Gone | ジョブの結果が48時間の保存期間を過ぎています。 |
| 429 Too Many Requests | リクエストの上限を超えました。少し待ってから再試行してください。 |
| 500 / 502 / 503 | サーバー、またはその背後の検証サービスが一時的に利用できません。 |
リクエストの上限
すべてのレスポンスにRateLimit-Limit、RateLimit-Remaining、RateLimit-Resetのヘッダー（RFCの表記）が入ります。これを使ってリクエストの間隔を調整できます。RateLimit-Resetは、現在の時間枠がリセットされるまでの秒数です。
| 区分 | 上限 |
|---|---|
| すべてのエンドポイント（初期値） | 300リクエスト / 15分 |
| ジョブの作成（POST /v1/verify-batch、POST /v1/catchall） | 30リクエスト / 15分 |
| ジョブの確認（GET /v1/jobs/:id、GET /v1/jobs/:id/results） | 600リクエスト / 15分 |
| 一括チェックの1ジョブあたりの最大メールアドレス数 | 50,000 |
| 結果の保存期間 | 48時間 |
ジョブは作成するよりも確認する回数の方が多いため、上限を3つに分けています。ジョブの実行中は、数秒ごとに状況を確認することもあります。600 / 15 min（1分あたり約40回）の上限なら、サーバーに過度な負担をかけずに、余裕を持って確認できます。
もっと高い上限が必要ですか？
確認済みの連携パートナーには、上限の引き上げを日常的に行っています。
429レスポンスの構造
上限に達すると、APIは次のボディとともにHTTP 429エラーを返します。
{
"success": false,
"message": "Developer API rate limit exceeded"
}再試行する前に、RateLimit-Resetヘッダーに書かれた秒数（時間枠がリセットされるまでの時間）だけ待ってください。
APIをつなぐ準備はできましたか？
APIキーは数秒で作成できます。無料のお試しクレジットが付いているので、支払いの前にすべてを最初から最後まで試せます。