Define the contract before writing code
Your endpoint should expose a normalized shape that does not change when the upstream provider does. Accept a JSON body with a single email field, and return the fields callers actually act on: the normalized email, status, reason, an optional suggestion, and a timestamp. Pass through VeriDock's four statuses unchanged since they already map cleanly to actions.
- POST /v1/emails/verify with body { email: string }.
- 200 with { email, status, reason, suggestion, checkedAt } on success.
- status is one of deliverable, undeliverable, risky, unknown.
- Every error body is { error, message } with a stable, documented error code.
Pick synchronous or asynchronous per request shape
The shape of the input decides the design. One address is a short request that fits in a normal HTTP round trip, so answer it directly. A list is not: thousands of addresses take minutes, and holding a connection open that long loses everything on a network blip. Accept the list, return a job id, and let the client come back for the result.
The diagram shows both lanes. The rest of the guide builds the top one in full and then the bottom one in outline.
A synchronous endpoint in Express
For one address at a time, a synchronous handler is the simplest correct design. Validate the body, call the provider with a timeout, and map every upstream failure to your own error code so clients never see raw provider responses.
Two details in the code are easy to get wrong. The key comparison uses timingSafeEqual and refuses to match when no key is configured, so a missing environment variable cannot turn into an open endpoint. And the fetch is wrapped in try/catch, because a timeout is a thrown exception, and you want it to become a 502 you chose, not a generic 500.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const app = express();
app.use(express.json({ limit: "10kb" }));
const fail = (res, status, error, message) => res.status(status).json({ error, message });
// Constant-time compare; never matches when INTERNAL_API_KEY is unset.
const sameKey = (a = "", b = "") => Boolean(b) && a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
const requireApiKey = (req, res, next) =>
sameKey(req.get("x-api-key"), process.env.INTERNAL_API_KEY) ? next() : fail(res, 401, "unauthorized", "missing or invalid key");
app.post("/v1/emails/verify", requireApiKey, async (req, res) => {
const email = typeof req.body?.email === "string" ? req.body.email.trim().toLowerCase() : "";
if (!email || email.length > 254) return fail(res, 400, "invalid_request", "email is required");
let upstream;
try {
upstream = await fetch(`https://app.veridock.io/v1/verify?email=${encodeURIComponent(email)}`, {
headers: { Authorization: `Bearer ${process.env.VERIDOCK_API_KEY}` },
signal: AbortSignal.timeout(10_000),
});
} catch {
return fail(res, 502, "verifier_unavailable", "verification timed out");
}
if (upstream.status === 429) {
res.set("Retry-After", upstream.headers.get("retry-after") ?? "5");
return fail(res, 503, "verifier_busy", "try again shortly");
}
if (upstream.status === 400) return fail(res, 400, "invalid_request", "email could not be parsed");
if (!upstream.ok) {
// 401 and 402 mean your key or credits, which the caller cannot fix. Alert yourself, hide the detail.
console.error("verifier error", upstream.status);
return fail(res, 502, "verifier_unavailable", "verification is temporarily unavailable");
}
const { status, reason, suggestion } = await upstream.json();
res.json({ email, status, reason, suggestion, checkedAt: new Date().toISOString() });
});
app.listen(3000);Translate provider errors into your own
Your callers should never have to read VeriDock's documentation to understand your API. Map the provider's failures to a small set of codes you control, and keep the mapping in one place so it is easy to audit.
The important case is the one the caller cannot fix. A 401 means your provider key is wrong or revoked, and a 402 means your credits or spend cap are exhausted. Both are your problem, so log them loudly, alert someone, and return a generic 502 to the caller. Passing a 402 through would tell every client your billing status.
Authentication, rate limits, and error codes
Require a key on your endpoint too, even for internal callers, so you can see which service generated load and revoke access individually. Apply a per-caller rate limit and return 429 with a Retry-After header when it is exceeded. VeriDock uses 429 for its own limits, and your clients should see the same convention.
VeriDock's limits are on concurrent requests, not requests per minute, and they depend on the plan: from 2 at the free level up to 100 on the largest. A wrapper that fans out freely will hit them first, so cap your own concurrency below the number on your plan and queue the rest.
- 400 invalid_request: body missing or email not a string.
- 401 unauthorized: key missing or revoked.
- 429 rate_limited: caller exceeded its quota, with Retry-After.
- 502 and 503: provider failed or is throttling; safe for clients to retry.
Cache by normalized address
Callers will verify the same address more than once: a user retries a form, two services check the same lead. Cache the result by normalized address so repeats never leave your network. VeriDock does not bill a re-verification of the same address within 30 days, so the provider side is already cheap; the cache saves latency and concurrency slots.
Keep the cache window short for risky and unknown results, since those can change quickly, and longer for deliverable and undeliverable. Never cache a failure: a 502 from a bad minute should not become a bad answer for the next hour.
When asynchronous processing fits better
A request with 10,000 addresses would hold a connection open for minutes. Instead, accept the list, return 202 with a job id, and let a worker process it. Clients poll a status endpoint or receive a webhook when the job completes.
VeriDock already supports this shape for bulk work: you create a job with an array of addresses or a CSV upload and an optional webhook_url, then poll the job or wait for the webhook. Webhook deliveries are signed with an HMAC in the X-VeriDock-Signature header, which you should verify against the raw body before trusting them. Results can be downloaded as CSV or streamed as NDJSON, filtered by status. Your endpoint can delegate the heavy lifting and simply mirror the job to your own clients.
Synchronous for one address with a hard timeout; asynchronous with a job id for anything that arrives as a list.
Test it without spending credits
Use a vd_test_ key for the provider call in development and CI. Test keys return deterministic fixtures and never consume credits, so your contract tests are repeatable and free.
Test the error paths on purpose, because they are where wrappers break. Point the provider URL at an unreachable host to check the timeout mapping, and stub a 429 with and without a Retry-After header to check that it passes through or falls back to your default.
- Missing, empty and 255-character emails each return 400.
- A request with no key, and one with the wrong key, both return 401, even when INTERNAL_API_KEY is unset.
- A provider 402 reaches the caller as a generic 502 and writes a log line you would notice.
- A provider 429 reaches the caller as 503 with Retry-After.
Key takeaways
0/5Try it on a real address
Run syntax, DNS, MX, disposable, and role checks on any address. No signup needed.
Enter an address and press Check.
Runs real syntax, DNS and mail-server checks.
This demo checks syntax, domain, mail server, disposable and role-address rules. Sign up free for live mailbox checks.
Frequently asked questions
Verify addresses with one API call.
250 free checks to start, no card required. Unknown results are never billed.