メールチェックAPIリファレンス

認証

POST /v1/email/validateは、X-Api-Keyヘッダーでオリジンロックされた公開可能キーを受け付けます — GET /v1/geoと同じキー種別と許可オリジンのモデルです。このページのその他すべてのエンドポイント(一括チェック、リストジョブ、サインアップチェック)は多数のアドレスや任意のIPを受け付けるため、Authorization: Bearerでシークレットキーが必要であり、必ずバックエンドから呼び出してください。公開可能キーを使うと403が返ります。

例

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

判定と理由コード

各条件は最低限の判定を定め、最も重いものが採用されます。reasonsには該当したすべてが重い順に列挙されます。フリーメールのアドレスを許容するかどうかはお客様の判断に委ねられ、判定を変えることはありません。

一括チェック

POST/v1/email/batch

1回のリクエストで1〜100件のアドレスを、POST /v1/email/validateと同じチェックと結果形式でチェックし、入力順にアドレスごとの結果を返します。{ "emails": [...] }を送信してください。同じドメインのアドレスは1回のDNS検索を共有します。アドレスごとに1リクエストとして月間プラン上限に計上され、上限を超える一括チェックは429 monthly_limit_exceededで全体が拒否されます。1分あたりのレート制限に対しては、呼び出し全体が1リクエストとして数えられます。シークレットキー専用。

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

メールリストジョブ

POST/v1/email/jobs

最大100,000件のアドレスをバックグラウンドでチェックします。JSON { "emails": [...], "filename": "..." }、または最大10 MBのtext/csv本文を送信してください:見出しがemail(e-mail、email address、email_address、mailも可、大文字小文字は区別しない)の列が使われ、該当する見出しがなければ先頭列が使われます。区切り文字はカンマ、セミコロン、タブを自動検出します。ジョブは作成時に課金されます — 重複を除いたアドレス(完全一致)ごとに1リクエストなので、重複もチェックされますが課金は1回です — 月間上限を超えるリストは全体が拒否されます。再試行後もジョブの一部を処理できなかった場合、ジョブはfailedとなり、未処理分のクレジットは返還されます。ジョブオブジェクトとともに202を返します。シークレットキー専用。同じジョブはダッシュボードのEmail listsページからもアップロード・ダウンロードできます。

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

ジョブのステータス

GET/v1/email/jobs/{id}

同じジョブオブジェクトを返します。statusがcompletedになるまでポーリングしてください。ポーリングは課金されません。

ジョブの結果

GET/v1/email/jobs/{id}/results

送信された各行に対して1行ずつ、送信順(重複を含む)のCSVをダウンロードします。列:email、normalized_email、verdict、reasons、syntax_valid、is_disposable、disposable_source、is_free_provider、is_role_account、did_you_mean、mx_status、mx_host。reasonsはセミコロン区切り、空のセルはnullを意味し、構文上無効なアドレスではmx_statusは空です(検索を行っていないため)。=、+、-、@で始まる無効なアドレスには、表計算ソフトが数式として実行しないようにアポストロフィが先頭に付けられます。ジョブ完了までは409、期限切れ後は410。ダウンロードは課金されません。

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

サインアップチェック

POST/v1/signup/check

サインアップフォームの送信時にバックエンドから、メールアドレスとIPに基づいてサインアップを1回の呼び出しでスコアリングします(ブラウザで計算した判定は偽装される可能性があります)。{ "email": "...", "ip": "...", "userAgent": "..." }を送信してください — userAgentは任意です。レスポンスには、メールチェックの完全な結果(email)、IPの国とASN、およびセキュリティデータを含むプランではVPN/Tor/データセンター/脅威の指標(ip)、公開登録データ(RDAP)に基づくメールドメインの経過日数(emailDomainAgeDays。不明な場合と著名な一般消費者向けプロバイダーではnull)、0〜100のスコア(下記の理由ごとの重みの合計、上限100)、および判定(60以上はreject、25以上はreview、それ以外はaccept)が含まれます。セキュリティデータのないプランでは、ip.securityはnullとなり、スコアはメールのシグナルのみを使い、reasonsにip_security_unavailableが含まれます。1リクエストとして計上されます。シークレットキー専用。

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

制限

チェックしたアドレスはすべて、プラン共通の月間上限に対して1リクエストとして計上されます — 単一チェック、一括チェックの各アドレス、リストジョブの重複を除いた各アドレス — サインアップチェックは1リクエストです。一括チェックとリストジョブは全体が受け付けられるか拒否されるかのいずれかで、部分的に処理されることはありません。1分あたりのレート制限はアイテム数ではなくHTTP呼び出し数で数えます。最大100件のIPまたはメールアドレスを含むバッチは1リクエストとして数えられ、各アイテムは引き続き月間リクエスト上限に個別に計上されます。リストジョブのアップロードと結果はジョブ作成から7日後に削除されます。DNS検索には短い時間枠があり、失敗やタイムアウトの場合はエラーではなく、mx.status unknownと理由dns_unavailableに縮退します。使い捨てドメインのデータは、コミュニティが管理する3つのオープンソースリストを統合したもので、数時間ごとに更新され、掲載ドメインを扱っていることが観測されたメールサーバーで拡張されます — データソースを参照してください。非常に新しい使い捨てプロバイダーは、まだ検出されない場合があります。すべてのチェックはドメインとアドレスのレベルで行われます。メールボックスには一切接続しないため、どの結果もメールボックスの存在、所有者、メールが届くことを証明するものではありません。