// guide
Integrate the pingutil email verification API end to end
For backend developers adding mailbox verification to a signup form, CRM sync or import job · Updated · 7 min read
I wired up an email verification API in an afternoon, then spent a week on the parts the quickstart skipped: timeouts, unknown results, rate limits and a quota that ran out mid-import.
Integrating pingutil's email verification takes one call, POST https://pingutil.com/v1/verify with { "email": "..." } and a Bearer key, and four branches: accept valid, reject invalid, apply a policy to risky, and treat unknown as "no answer yet". The production work is everything around that: a timeout so a slow mail server can't stall your signup, retries only for errors that can succeed on retry, a clean stop on quota_exceeded, and your own cache so you don't spend the 300 daily verifications on addresses you checked yesterday.
This guide walks through all of it in order, with a complete Node client at the end.
What this problem costs you
Verification looks simple until it's in production. The failures are predictable:
- Signups hang. A mailbox check talks to the recipient's mail server over SMTP. Some servers are slow. Without a timeout, your signup request waits on someone else's infrastructure.
- Real users get rejected. Code that treats anything other than
validas bad rejects catch-all company domains and servers that refused to answer. That's a lot of real customers. - Retry storms. A loop that retries every non-200 hammers the API after the daily quota is gone, gets the same 429 every time, and fills your logs.
- Budget burnt on duplicates. Import jobs re-verify the same addresses every night because nobody stored the last result.
None of these are hard to fix. They just need to be decided up front. The integration checklist is a short version of this guide if you want a list to work from.
How pingutil solves it
1. Get a key and keep it server-side
Sign in at the dashboard (passwordless) and create a key. The raw key is shown once. Store it as a secret, for example PINGUTIL_KEY, and only call the API from your backend. An account can have up to 3 active keys, which is enough for separate production, staging and batch-job keys. They share one rate limit and one set of daily budgets.
2. Make the first call
curl -X POST https://pingutil.com/v1/verify \
-H "Authorization: Bearer pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{ "email": "jane@northwind-example.com" }'
An illustrative response:
{
"email": "jane@northwind-example.com",
"input": "jane@northwind-example.com",
"status": "valid",
"reason": "mailbox_exists",
"score": 95,
"did_you_mean": null,
"checks": {
"syntax": true,
"disposable": false,
"free_provider": false,
"role_based": false,
"randomized": false,
"domain_exists": true,
"has_mx": true,
"mailbox": "exists",
"catch_all": false
},
"mx_host": "mx1.northwind-example.com",
"smtp": { "code": 250, "enhanced": "2.1.5", "message": "OK" },
"cached": false,
"checked_at": "2026-11-16T09:12:00.000Z"
}
GET /v1/verify?email=... works too. For lists, POST /v1/verify/batch takes { "emails": [...] } with up to 50 addresses and returns { "results": [...] }.
3. Branch on status, then reason
status is the decision. reason tells you why, and it's what you show in logs or use for finer policy. score (0 to 100) is a confidence that mail would reach a person; use it for sorting, not as your main switch. Email verification statuses explained covers each reason in detail.
4. Handle errors by type
Every error has the same shape: { "error": "...", "message": "...", "retry_after_seconds"?: n }. Decide per error code, not per HTTP status, because both limits use 429.
5. Set timeouts and a fallback
Pick a timeout per context. At signup, a few seconds and then fall back to accepting the address (and re-checking later). In a background import, you can wait much longer.
6. Cache on your side
pingutil caches definitive results for 30 days and greylisted, blocked or rate-limited answers for an hour, so a repeat check is fast. It still counts toward your daily 300. Store status, reason and checked_at per address, and only re-verify when your stored result is older than your own threshold.
Decision table: statuses and errors to actions
| Result | Signup form | List import or CRM sync |
|---|---|---|
valid |
Accept | Keep, mark verified |
invalid with did_you_mean set |
Ask "Did you mean ...?" | Flag for a human, don't auto-correct |
invalid (mailbox_not_found, no_mx, no_domain, disposable_domain, ...) |
Reject with a clear message | Suppress |
risky, accept_all |
Accept, rely on your confirmation email | Keep in a separate, cautious segment |
risky, role_based |
Accept or ask for a personal address, by product type | Keep for shared-inbox use, exclude from personal outreach |
risky, randomized_local_part or mailbox_full |
Accept with confirmation, or review | Hold |
unknown (any reason) |
Accept, re-check in the background | Re-check in an hour or more |
HTTP 400 invalid_input |
Treat as a bad address | Log and skip the row |
HTTP 401 unauthorized |
Alert: key missing or revoked. Fail open | Stop the job |
HTTP 413 payload_too_large |
Not expected for one address | Split the batch |
HTTP 429 rate_limited |
Fail open, re-check later | Wait retry_after_seconds, retry |
HTTP 429 quota_exceeded |
Fail open, re-check after 00:00 UTC | Stop and resume tomorrow |
HTTP 503 quota_unavailable, 5xx, network error, timeout |
Fail open | Retry with backoff, a few times |
"Fail open" means accept the signup and verify later. A verification outage shouldn't become a signup outage.
Complete example: a production client in Node
This client covers timeouts, retry rules, daily-quota handling and a local cache. store is any key-value store you already have (Redis, a database table). It needs Node 18 or later for fetch and AbortSignal.timeout.
const API = 'https://pingutil.com/v1/verify';
const KEY = process.env.PINGUTIL_KEY; // pk_live_...
const MAX_AGE_MS = 14 * 24 * 3600 * 1000; // re-verify after 14 days
class QuotaExceeded extends Error {}
class Unauthorized extends Error {}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function callVerify(email, timeoutMs) {
const res = await fetch(API, {
method: 'POST',
headers: { authorization: `Bearer ${KEY}`, 'content-type': 'application/json' },
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(timeoutMs),
});
if (res.ok) return res.json();
const body = await res.json().catch(() => ({}));
const err = new Error(body.message || `HTTP ${res.status}`);
err.code = body.error;
err.status = res.status;
err.retryAfter = body.retry_after_seconds;
if (body.error === 'quota_exceeded') throw new QuotaExceeded(err.message);
if (res.status === 401) throw new Unauthorized(err.message);
throw err;
}
function retryable(err) {
if (err.name === 'TimeoutError' || err.name === 'TypeError') return true; // timeout, network
return err.code === 'rate_limited' || err.code === 'quota_unavailable' || err.status >= 500;
}
export async function verifyEmail(email, { store, timeoutMs = 4000, attempts = 1 } = {}) {
const key = `verify:${email.trim().toLowerCase()}`;
const cached = store && (await store.get(key));
if (cached && Date.now() - Date.parse(cached.checked_at) < MAX_AGE_MS && cached.status !== 'unknown') {
return { ...cached, source: 'local_cache' };
}
for (let i = 0; i < attempts; i++) {
try {
const result = await callVerify(email, timeoutMs);
if (store) await store.set(key, result);
return result;
} catch (err) {
if (err instanceof QuotaExceeded || err instanceof Unauthorized) throw err;
if (err.code === 'invalid_input') {
return { status: 'invalid', reason: 'invalid_syntax', input: email };
}
if (!retryable(err) || i === attempts - 1) throw err;
const wait = err.retryAfter ? err.retryAfter * 1000 : 500 * 2 ** i;
await sleep(wait);
}
}
}
// Signup: short timeout, one attempt, fail open.
export async function checkAtSignup(email, store) {
try {
const r = await verifyEmail(email, { store, timeoutMs: 4000, attempts: 1 });
if (r.status === 'invalid') return { allow: false, reason: r.reason, didYouMean: r.did_you_mean ?? null };
return { allow: true, status: r.status, recheck: r.status === 'unknown' };
} catch (err) {
return { allow: true, status: 'unchecked', recheck: true, error: err.code || err.name };
}
}
// Background job: longer timeout, retries, stop on quota.
export async function verifyForImport(email, store) {
return verifyEmail(email, { store, timeoutMs: 60_000, attempts: 4 });
}
The signup path makes one attempt and fails open, so a slow mail server never blocks a customer. The import path retries transient failures with backoff (or retry_after_seconds when the API provides it) and lets QuotaExceeded bubble up so the job can save its position and stop. Results with status: unknown are never served from the local cache, so they get re-checked the next time.
Edge cases and limits
- Catch-all domains are never
valid. If the server accepts any address, pingutil reportsrisky/accept_all. Providers that accept everything at the SMTP stage (Yahoo, for example) also come back that way. Plan a policy for it instead of treating it as an error. unknownis common on some servers. Greylisting, sender blocks and timeouts all end there. See greylisting and email verification for why retrying an hour later often works.- Limits. 60 requests a minute per account, shared by all keys. On the Free plan, 300 verifications a day and 3,000 a month per account, API and dashboard CSV uploads combined, resetting at 00:00 UTC and on the 1st. Enterprise has custom limits. Every address counts, including ones answered from pingutil's cache. A batch is reserved as a whole, so a 50-address batch with 20 left in the budget fails entirely.
- There's also a per-recipient-domain cap. To avoid hammering one company's mail server, pingutil limits how many checks go to one domain per day (free webmail excluded). Large lists concentrated on one company domain can see more
unknownresults. - No webhooks, no SDK. Calls are synchronous and the client above is plain
fetch. The OpenAPI spec at/openapi.jsonworks with code generators if you want typed clients. - Verification isn't ownership. A
validresult means the mailbox exists. Only a confirmation email proves the person signing up controls it.
If you also screen signups with the fast lookup endpoint, signup risk scoring shows how to combine the two, and the SaaS signup protection use case puts it in context.
Next step
Try a few addresses on the email verification page, then create a key on the dashboard and drop the client above into your codebase. The API reference has the full schema for /v1/verify and /v1/verify/batch.
Questions people ask
- What should I do with an unknown verification result?
- Treat it as no answer, not as a bad address. Accept the signup or keep the contact, and re-check later. Unknown usually means the mail server greylisted, rate-limited or blocked the check, and many of those clear up within an hour.
- What is the difference between rate_limited and quota_exceeded?
- Both are HTTP 429. rate_limited means you sent more than 60 requests in a minute, so wait retry_after_seconds and try again. quota_exceeded means the daily or monthly budget is used up, and retrying won't help until it resets (00:00 UTC daily, the 1st of the month for monthly).
- Should I cache verification results on my side?
- Yes. pingutil caches results for 30 days, but every address you send still counts toward your Free plan budget of 300 verifications a day (3,000 a month). Keeping your own record of recent results means you don't spend budget re-checking the same address.