Quickstart

Create an API key from the dashboard, then call /v1/verify. That is the whole integration.

curl "https://api.veridock.io/v1/verify?email=jane.doe@acme.com" \
  -H "Authorization: Bearer vd_live_••••••••••••"

Authentication

Every request needs a bearer token in the Authorization header. Keys are prefixed vd_live_ or vd_test_. Test keys return deterministic fixtures and never consume credits, so your CI can run against them.

Authorization: Bearer vd_live_••••••••••••

Each key has its own usage, rate limit, and optional spend cap. Never ship a live key to a browser; use a test key or proxy through your server.

Verify an address

GET /v1/verify?email={email}

POST /v1/verify with a JSON body {"email": "…"} is also accepted and behaves identically.

Response fields

{
  "email": "jane.doe@acme.com",
  "status": "deliverable",
  "reason": "accepted_email",
  "score": 97,
  "checks": {
    "syntax": true,
    "domain": true,
    "mx": true,
    "smtp": true,
    "disposable": false,
    "role_account": false,
    "catch_all": false,
    "free_provider": false
  },
  "domain": {
    "name": "acme.com",
    "mx": ["aspmx.l.google.com"],
    "provider": "google_workspace"
  },
  "suggestion": null,
  "billed": true,
  "duration_ms": 412
}

Statuses and reasons

Branch your code on status. Use reason when you want finer rules, for example allowing role accounts for B2B signups but rejecting disposable ones.

Bulk verification

Send an array of addresses or upload a CSV. Jobs run asynchronously, you can poll or receive a webhook, and results are available as CSV, JSON, or newline-delimited JSON filtered by status.

curl -X POST https://api.veridock.io/v1/bulk \
  -H "Authorization: Bearer vd_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "october-newsletter",
    "emails": ["a@acme.com", "b@acme.com", "c@example.org"],
    "webhook_url": "https://example.com/hooks/veridock"
  }'

# → { "id": "job_8f2k1", "status": "queued", "total": 3 }

Webhooks

Pass webhook_url when creating a job and we POST the job object to it on completion. Every delivery is signed with your webhook secret in the X-VeriDock-Signature header (HMAC-SHA256 of the raw body). We retry failed deliveries with exponential backoff for 24 hours.

import crypto from "node:crypto";

export function verifySignature(rawBody: string, header: string, secret: string) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Errors

Errors return a JSON body of the shape {"error": {"code", "message"}}. Failed requests are never billed.

Rate limits

Limits are on concurrent in-flight requests per key, not requests per minute, because SMTP checks vary in duration. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and, on 429, Retry-After.

SDKs and integrations

The API is plain HTTPS and JSON, so any HTTP client works. Official packages wrap it with types and retries.

Something missing? Tell us and we will add it.