Know an address exists before you send a thing.

API

JSON over HTTPS, one bearer key per product. The same API runs our own products today. Early-access keys come with your base URL; examples use $VG_BASE.

Quick start

curl -s "$VG_BASE/v1/check" \
  -H "Authorization: Bearer $VG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.cole@acme-dental.example"}'

import os, requests

r = requests.post(
    f"{os.environ['VG_BASE']}/v1/check",
    headers={"Authorization": f"Bearer {os.environ['VG_KEY']}"},
    json={"email": "jane.cole@acme-dental.example"},
    timeout=70,
)
result = r.json()
if r.status_code == 200 and result["status"] == "valid":
    send_later(result["email"])  # sendable for 30 days from checked_at

const r = await fetch(`${process.env.VG_BASE}/v1/check`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane.cole@acme-dental.example" }),
});
const result = await r.json(); // 202 = still checking: poll /v1/jobs/{job_id}

Response, 200:

{
  "email": "jane.cole@acme-dental.example",
  "status": "valid",
  "reason": null,
  "smtp_code": 250,
  "smtp_text": "2.1.5 OK",
  "mx_host": "mx.acme-dental.example",
  "checked_at": "2026-09-28 11:02:13.482117+00:00",
  "job_id": "5b0e7d0c-3f6a-4c55-9a1e-0f3c2d8b7a14"
}

Keys

Send Authorization: Bearer vg_… on every request except health and the OpenAPI document. Each product gets its own key. We store only a SHA-256 hash, so a key is shown once, when it is issued; if you lose it, we revoke it and issue another. Jobs are private to the key that created them.

POST /v1/check

Checks one address and waits up to 60 seconds for the answer. Most answers take a few seconds. A slow server or greylisting returns 202 with the item still pending or checking; keep the job_id and read it later.

{ "email": "jane.cole@acme-dental.example" }

POST /v1/jobs

Queues up to 5,000 addresses and returns at once. Addresses that aren’t addresses come back as bad_syntax without a check.

{ "emails": ["jane.cole@acme-dental.example", "accounts@acme-dental.example"] }

{ "job_id": "9d2f4b61-8c0e-4e7a-b3d5-2a6f1c9e0b87", "total": 2 }

GET /v1/jobs/{id}

The job and its results so far, up to 1,000 per page: pass offset and limit, and follow next_offset (null on the last page). done counts finished items across the whole job; poll until it equals total. A job created with a different key returns 404.

{
  "id": "9d2f4b61-8c0e-4e7a-b3d5-2a6f1c9e0b87",
  "requested_by": "your-product",
  "total": 2,
  "done": 2,
  "created_at": "2026-09-28 11:04:50.017342+00:00",
  "items": [
    { "email": "jane.cole@acme-dental.example", "status": "valid", "reason": null,
      "smtp_code": 250, "smtp_text": "2.1.5 OK", "mx_host": "mx.acme-dental.example",
      "checked_at": "2026-09-28 11:05:02.311904+00:00" },
    { "email": "accounts@acme-dental.example", "status": "invalid", "reason": null,
      "smtp_code": 550, "smtp_text": "5.1.1 User unknown", "mx_host": "mx.acme-dental.example",
      "checked_at": "2026-09-28 11:05:06.908215+00:00" }
  ]
}

Result fields

status

pending · checking · valid · invalid · catch_all · unknown · suppressed · bad_syntax. Only valid is sendable, for 30 days from checked_at.

reason

Why, when the status alone doesn’t say: domain accepts any address, no_mx, mail server unreachable, answered by a different MX than the probe, microsoft 5.4.1 on every address: not trusted, catch-all undecided (451). Otherwise null.

smtp_code, smtp_text

The server’s own reply to RCPT TO, so you can see the evidence rather than take our word for it.

mx_host

The mail server that answered.

checked_at

When the answer came back (UTC). Empty while pending.

flags

role (info@, sales@…), free_mail (Gmail, Outlook…), disposable (throwaway domains, from a public list) and plus_address (name+tag@). Worked out from the address alone; a flag never changes the verdict.

suggestion

A likely intended address when the domain looks like a typo of a common provider, such as jane@gmial.com → jane@gmail.com. Otherwise null.

score, reasons

0–100 for sorting, never a second opinion: valid 95, catch_all 45, unknown 25, everything else 0; a role address costs 5, a disposable domain caps it at 10. reasons lists every rule that applied, e.g. ["status_valid", "role_address"]. Empty while pending.

Errors

Limits, and why they’re low

Checks leave from one IP address with a published name, at up to 20 a minute, one conversation per domain at a time. A circuit breaker pauses everything if servers start refusing us. That pace keeps us welcome on the servers you want answers from. Hand-started checks jump the queue ahead of background work.

GET /v1/status · /v1/health · /v1/openapi.json

/v1/status returns queue counts, checks in the last hour, and whether the sending IP appears on any of eight blocklists. /v1/health needs no key. /v1/openapi.json is the machine-readable version of this page.