# Vouch

> Vouch is an email verification API by Datapad. A single authenticated GET request runs a five-stage pipeline — syntax, MX lookup, a live SMTP RCPT TO probe, and catch-all detection — and returns a deliverability verdict, a 0–100 score, and a full per-check breakdown. Vouch never sends an email to verify one.

Vouch verifies an address by opening a real SMTP conversation with the recipient's mail server and issuing the RCPT TO command — the same step a real send uses to learn whether a mailbox exists — then quitting before any message body (DATA) is transmitted. The result is a single JSON object you can branch on directly in a signup or list-cleaning flow.

## How it works

- Syntax: RFC-grade parse with IDN normalization. Malformed input stops here, before any network call.
- MX lookup: mail hosts are resolved and cached, priority-ordered. No MX records means undeliverable.
- SMTP probe: EHLO, MAIL FROM, RCPT TO against the real MX host. Vouch never sends DATA and always QUITs.
- Catch-all: a second RCPT TO to a random local-part on the same connection. Domains that accept everything are flagged risky, not deliverable.
- Verdict: the collected signals map through one deterministic table to a status, a reason code, and a 0–100 score.

## Verdicts

- deliverable: mailbox confirmed over SMTP.
- risky: accepts mail, but with a caveat — a catch-all domain, a role account, or greylisting.
- undeliverable: bad syntax, no MX records, or a 550 rejection.
- unknown: timeout or connection trouble; retry rather than guess.

## API

- Full reference: https://vouch.fast/docs · OpenAPI 3.1 spec: https://vouch.fast/openapi.json
- Endpoint: GET /v1/verify?email=you@example.com
- Auth: `Authorization: Bearer <api-key>` header (a `?apikey=` query parameter is also accepted).
- Response fields: email, user, domain, status, reason, score, checks{}, flags{}, didYouMean, mxHost, meta{}.
- Flags: disposable, role-account and free-provider detection. didYouMean returns a typo suggestion (e.g. gamil.com → gmail.com).
- Performance: about one second typical; five-second per-step timeout, eight-second total budget, cached MX, at most three hosts tried.

## Bulk verification

- Upload a CSV or Excel (.xlsx) list — in the dashboard or via the API — and Vouch verifies the whole list as a background job, then returns a downloadable results CSV.
- De-duplication: every cell is scanned and duplicate addresses are removed before verification. An intake report (candidates found, duplicates removed, unique count) comes back immediately, and you are only charged for unique addresses.
- Parallelism: unique addresses are verified concurrently (a configurable cap), while the per-mail-host limit keeps each receiving server politely handled.
- POST /v1/batches — multipart upload (form field `file`); returns a jobId, the unique total, and the de-dup report.
- GET /v1/batches/:id — job status and progress (status, total, processed, verdict counts).
- GET /v1/batches/:id/results — the results CSV once the job is complete (columns: email, status, reason, score, disposable, roleAccount, freeProvider, catchAll, didYouMean, mxHost).

## Free list health check

- POST /v1/health-check — JSON body { "emails": [...] } (up to 50,000 addresses). Free, no credit charge, no SMTP: a structural-only diagnosis (syntax, disposable domains, MX records, role accounts). Returns 202 with a jobId; the check runs as a background job.
- GET /v1/health-check — poll the job; once status is "complete" it carries an aggregate-only report: counts and percentages per category plus roll-ups (summary.unhealthy is the headline). Never per-address verdicts — structurally clean addresses stay "okUnverified" until a full SMTP verification confirms them.
- One free check per API key; a repeat POST replays the existing job (alreadyUsed: true). A failed job doesn't burn the allowance.

## Credits

- Free tier: every new account starts with 250 free credits, granted automatically at signup — no card required. After that, credits are pre-paid pay-as-you-go and never expire.
- 1 credit per completed verification, whatever the verdict; Vouch-side 5xx errors are never charged. Batches charge per unique address as it completes; when the balance runs out, remaining rows are marked "skipped" and not charged.
- GET /v1/credits — the calling key's balance as { enforced, creditsRemaining }; a credit-free pre-flight before starting a batch, not counted against the rate limit. When enforced is false, creditsRemaining is null (treat as unlimited).
- An empty balance returns 402 insufficient_credits; successful /v1/verify responses carry an X-Credits-Remaining header.

## MCP server

- @datapad-nl/vouch-mcp (npm) gives any MCP client — Claude Desktop, Claude Code, Cursor, Cline — a verify_email tool backed by this API. The server runs locally via npx; the API key is sent only to the Vouch API over HTTPS.
- Config: command "npx", args ["-y", "@datapad-nl/vouch-mcp"], env { "VOUCH_API_KEY": "vch_live_…" }. Claude Code one-liner: claude mcp add vouch --env VOUCH_API_KEY=<key> -- npx -y @datapad-nl/vouch-mcp
- The tool takes { "email": "..." } and returns the same JSON verdict as GET /v1/verify (1 credit per call).

## Links

- Homepage: https://vouch.fast/
- Live demo (no account needed): https://vouch.fast/#try
- API docs: https://vouch.fast/docs
- OpenAPI spec: https://vouch.fast/openapi.json
- MCP server: https://vouch.fast/#mcp · npm package: https://www.npmjs.com/package/@datapad-nl/vouch-mcp
- How it works: https://vouch.fast/#how
- Features: https://vouch.fast/#features
- Pricing: https://vouch.fast/#pricing
- FAQ: https://vouch.fast/#faq
- Built by Datapad: https://www.datapad.nl

## Contact

- Email: hello@datapad.nl