Authentication

Programmatic calls: send your live API key in the Authorization header:

Authorization: Bearer va_live_xxx

Generate and rotate keys under Dashboard → API Keys. Keys are created server-side and shown there so you can copy them at any time.

Validation types & performance

The action you pass determines what runs and how it is billed. Single checks (email-check) are synchronous; batch jobs are asynchronous.

• evaluate — evaluate — sample-based list evaluation (free preview, no per-email credits). Fast.
• dc — dc — deliverability check (mailbox/MX/SMTP signals). Returns a deliverability status.
• td — td — threat detection (assigns a threat score/level).
• dt — dt — full verification (deliverability + threat in one pass). Most thorough.

Latency grows with depth: dt > dc/td > evaluate. For large lists prefer batch jobs and rely on the webhook to learn when results are ready.

POST /validate/email-check

Validate a single email (session cookie, API key, or action "evaluate" for public Quick Try).

POST /api/validate/email-check
{ "email": "[email protected]", "action": "evaluate" }

Example response

{
  "email": "[email protected]",
  "status": "deliverable",
  "recommendation": "safe_to_send",
  "score": 5,
  "rating": "excellent",
  "threat_level": "none",
  "domain": "example.com",
  "provider": "google",
  "validation_type": "verification"
}

POST /validate/batch

Start an asynchronous job over a previously uploaded list. Returns immediately with an acknowledgement; the job completes in the background.

POST /api/validate/batch
Authorization: Bearer va_live_xxx
{ "listid": "<list-uuid>", "action": "dt" }

200 OK
{ "message": "Batch validation started - this may take a while - check back later" }

Batch jobs are processed asynchronously. Configure a webhook to be notified on completion, then retrieve or download the results by job id.

Bulk jobs

• POST /list — upload CSV (base64 filepath)
• POST /validate/batch — evaluate, dt, dc, td
• GET /list/:id — list status and summary JSON
• GET /job/:id/download — CSV export (segment via ?type=)

Downloading results

Export a completed job as CSV. Use the type query parameter to choose which segment of contacts to download. Omit it (or use all) for the full report.

GET /api/job/{id}/download?type=maxreach
GET /api/job/{id}/download?type=bestreach
GET /api/job/{id}/download?type=all
GET /api/job/{id}/download?type=maxreach&provider=Gmail

• type=all — Full report: every row with all columns (email, recommendation, score, rating, status, reason, threat level, threat score, domain, provider).
• type=bestreach — Safe to send only: email-only export of the strongest-signal, deliverable contacts (lowest risk).
• type=maxreach — Safe + cautious: email-only export of likely-deliverable contacts, including catch-all and risk domains; undeliverable and high-risk contacts are excluded.
• provider — Optional filter (verification jobs) to a single email provider, e.g. provider=Gmail.

Webhooks

Configure one endpoint per account under Dashboard → API Keys. Only API-key-initiated validations fire webhooks. Single checks send the full result; batch jobs send a summary plus the job id.

Single payload

{
  "event": "validation.completed",
  "mode": "single",
  "validation_type": "verification",
  "status": "completed",
  "job_id": "<job-uuid>",
  "result": { "email": "[email protected]", "status": "deliverable", "...": "..." }
}

Batch payload

{
  "event": "validation.completed",
  "mode": "batch",
  "validation_type": "verification",
  "status": "completed",
  "job_id": "<job-uuid>",
  "emails_count": 50000,
  "summary": { "qty": 50000, "verification_job": { "...": "..." } }
}

Each delivery includes an X-Validationapp-Signature header: sha256=<HMAC-SHA256 of the raw request body using your signing secret>. Recompute and compare it to verify authenticity.

Deliveries time out after ~10s and are retried up to 3 times with backoff. Respond with a 2xx status to acknowledge.