Email Check API Reference

Authentication

POST /v1/email/validate takes an origin-locked publishable key via the X-Api-Key header — the same key type and allowed-origins model as GET /v1/geo. Every other endpoint on this page (batch, list jobs, signup check) accepts many addresses or an arbitrary IP, so it requires your secret key via Authorization: Bearer and must only be called from your backend; a publishable key gets a 403 there.

Example

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

Verdict and reason codes

Each condition sets a minimum verdict; the most severe one wins, and reasons lists all of them, most severe first. Whether a free-provider address is acceptable is left to you — it never moves the verdict.

Batch check

POST/v1/email/batch

Checks 1–100 addresses in one request with the same checks and result shape as POST /v1/email/validate, one result per address in input order. Send { "emails": [...] }. Addresses on the same domain share one DNS lookup. Counts one request per address against your monthly plan cap; a batch that would exceed the cap is rejected whole with 429 monthly_limit_exceeded. Toward the per-minute rate limit, the whole call counts as one request. Secret key only.

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"], ... }
  ]
}

Email list jobs

POST/v1/email/jobs

Checks up to 100,000 addresses in the background. Send JSON { "emails": [...], "filename": "..." } or a text/csv body of at most 10 MB: the column headed email (also e-mail, email address, email_address or mail, case-insensitive) is used, or the first column when no header names one; comma, semicolon and tab separators are detected. The job is charged when it is created — one request per distinct address (exact match), so duplicates are checked but charged once — and a list that would exceed your monthly cap is rejected whole. If part of a job cannot be processed after retries, the job is marked failed and the credits for the unprocessed part are returned. Answers 202 with the job object. Secret key only; the same jobs can also be uploaded and downloaded from the dashboard's Email lists page.

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

Job status

GET/v1/email/jobs/{id}

Returns the same job object. Poll it until status is completed; polling is not charged.

Job results

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

Downloads a CSV with one row per submitted row, in submission order — duplicates included. Columns: 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 is semicolon-separated, empty cells mean null, and mx_status is empty for syntactically invalid addresses (nothing was looked up). An invalid address that starts with =, +, - or @ is prefixed with an apostrophe so spreadsheet apps don't run it as a formula. 409 until the job has completed, 410 once it has expired. Downloading is not charged.

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

Signup check

POST/v1/signup/check

Scores a signup from its email address and IP in one call, from your backend when the signup form is submitted (a verdict computed in the browser can be forged). Send { "email": "...", "ip": "...", "userAgent": "..." } — userAgent is optional. The response contains the full email check result (email), the IP's country, ASN and — on plans that include security data — its VPN/Tor/datacenter/threat indicators (ip), the email domain's age in days from public registration (RDAP) data (emailDomainAgeDays, null when unknown and for well-known consumer providers), a 0–100 score (the sum of the reason weights below, capped at 100) and a verdict: reject at 60 or more, review at 25 or more, otherwise accept. On a plan without security data, ip.security is null, the score uses the email signals only, and reasons includes ip_security_unavailable. Counts as one request. Secret key only.

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

Limits

Every address checked counts as one request against your plan's shared monthly cap — a single check, each address in a batch, each distinct address in a list job — and a signup check is one request. Batches and list jobs are admitted or rejected whole, never partially fulfilled. The per-minute rate limit counts HTTP calls, not items: a batch of up to 100 IPs or email addresses is one request toward it, while each item still counts separately toward the monthly request cap. List-job uploads and results are deleted 7 days after the job is created. DNS lookups have a short time budget: when one fails or times out the result degrades to mx.status unknown and reason dns_unavailable rather than an error. Disposable-domain data is merged from three community-maintained open-source lists, refreshed every few hours and extended by mail servers observed to serve listed domains — see data sources. A very new disposable provider may not be flagged yet. All checks are domain- and address-level: no mailbox is contacted, so no result establishes that a mailbox exists, who owns it, or that mail to it will arrive.