Email Verification API: A Release Test

An email verification API is ready for production only when your workflow handles every result, timeout, retry, and correction without accidentally releasing a risky address. A successful request is not a successful control. Before launch, run a fixed test set through both real-time and batch paths, translate provider-specific results into your own policy states, preserve the raw evidence, and prove that the previous version can be restored.

Define the Decision Before Choosing the Endpoint

The business question is not "Can this API verify an email?" It is "What should our outbound system do with each returned state?" Write that decision table before connecting a provider.

A practical internal model needs at least four states:

This separation matters because providers use different labels. Kickbox returns deliverable, undeliverable, risky, and unknown from its single verification API. NeverBounce documents valid, invalid, disposable, catchall, and unknown in its single-check reference. ZeroBounce documents valid, invalid, catch-all, unknown, spamtrap, abuse, and do_not_mail in its real-time validation guide.

The labels are inputs. Your policy owns the decision.

Build a Fixed Release Test Set

A release test should use known cases that exercise every branch, rather than a convenient file dominated by valid addresses. Keep the test data controlled and approved. Include:

• Syntactically invalid addresses
• Valid addresses under your control
• Disposable addresses and role addresses
• Catch-all or accept-all domains
• Domains that produce slow or unknown responses
• Provider sandbox examples, where available
• Duplicate records and addresses already on your suppression list
• A plausible typo with a suggested correction
• Authentication failure, exhausted-credit, and malformed-response cases

Record the expected internal state for each row before the run. The test passes only when the workflow produces that state and the expected evidence. It does not pass merely because the vendor's response looks reasonable.

Use a unique test-run ID and preserve the original input. Kickbox notes that its response can include a normalized version of an address and recommends logging the submitted form for record keeping. Treat a suggested correction as evidence, not permission to overwrite a person's address. A human-approved or separately verified correction should create a new record of the change.

Test Real-Time and Batch Paths Separately

Real-time verification belongs where a decision is needed during capture or immediately before a record advances. Batch verification fits list imports, scheduled hygiene, and slower rechecks. They can share policy, but they are different operating paths with different waiting times and failure modes.

ZeroBounce says its real-time response can take from one to 30 seconds and that slow or greylisting mail servers can produce unknown; its guide points those conditions toward bulk revalidation. Kickbox allows a timeout parameter with a documented default of 6,000 milliseconds and maximum of 30,000 milliseconds. NeverBounce recommends treating request timeouts as unknown and warns that unknowns can occur more often through the single endpoint than through bulk verification in its verification guide.

Test both modes against the same policy cases, then compare:

• Result and reason returned
• Time to decision
• Number and timing of retries
• Credit or usage treatment
• Evidence stored
• Final sending eligibility

Do not require a website visitor to wait indefinitely for a receiving server. Equally, do not translate a fast timeout into "valid." The correct output is "no verified decision yet."

Map Provider Results Without Flattening Them

Create a versioned mapping table for each provider. Avoid a universal shortcut such as green, yellow, and red; it hides meaningful differences and makes a provider change dangerous.

A conservative starting point might map clearly deliverable or valid results to eligible, clearly invalid or undeliverable results to suppressed, and disposable, abuse, spam-trap, or do-not-mail findings to a named suppression reason. Catch-all, risky, and unknown need separate policies because they describe different boundaries.

NeverBounce defines catch-all as a domain-wide accept-all setting and unknown as a server that cannot be reached. Kickbox separately reports risky and unknown, and also exposes an accept_all field. ZeroBounce separates catch-all from unknown and from stronger warning categories. Those are not interchangeable signals.

Our view: any provider result that has no explicit, reviewed mapping should default to unknown and remain suppressed. Quietly treating a new label as eligible is a release defect, not a harmless fallback.

Store the provider name, endpoint or job type, raw result, reason or sub-status, internal state, mapping version, checked time, and decision time. That record lets you explain why an address moved.

Make Retries Idempotent

A retry must repeat the check without repeating its business effects. Otherwise a network interruption can create duplicate charges in your own ledger, repeated CRM updates, or multiple campaign enrollments even if the provider processed only one verification.

Assign each verification attempt an internal request key built from the record, normalized address fingerprint, policy version, and intended check window. Before creating a new job, check whether that key already has a completed or active attempt. Keep provider usage records separate from your workflow state so a retry cannot be mistaken for a new approval.

Set bounded retries for temporary failures and add increasing delay between attempts. Permanent authentication or request-format errors should stop immediately and alert an owner. A timeout remains unknown until a later response or approved recheck resolves it.

NeverBounce explicitly warns against calling its standard API from client-side code because that would expose sensitive credentials. Keep API keys in the server-side integration, limit access, and make credential failure visible. A hidden browser key turns a data-quality control into an account risk.

Preserve Suppression Through Every Transition

Verification must never erase an existing suppression reason. An address that appears technically deliverable may still be suppressed because of an unsubscribe, complaint, legal restriction, customer request, prior abuse signal, or internal account policy. Verification answers one narrow question; it does not overrule consent or contact governance.

Use an append-only suppression record with source, reason, effective time, owner, and release authority. When a result changes, calculate eligibility by combining verification state with all active suppression reasons. Require every export, CRM sync, and campaign loader to check that combined state.

Then test the negative path. Put a known suppressed address into the import, return a deliverable result from the test fixture, and confirm that it still cannot enter a campaign. Repeat the test through manual upload, scheduled batch, CRM-triggered flow, and retry completion. A control that works only on the main path is not ready.

Require Evidence and Fail Closed

Every release run should produce a small evidence package: test manifest, expected outcomes, raw provider responses, mapped outcomes, exceptions, retry history, suppression checks, approver, release time, and policy version. Keep secrets and unnecessary personal data out of the package while retaining enough detail to reproduce the decision.

Define explicit fail-closed conditions:

• Provider response cannot be parsed
• Result label is unmapped
• Request times out without a resolved follow-up
• Authentication or usage control fails
• Suppression service is unavailable
• Evidence write fails
• Policy version is missing

"Fail closed" means the affected records do not advance into sending. It does not have to stop every campaign. Isolate the failed branch, preserve the queue, alert the owner, and keep unaffected approved work separate.

A release dashboard should show counts by provider result and internal state, not just success rate. Sudden growth in unknowns, an empty suppression count, or a new result label should block approval until explained.

Prove Rollback Before Production

Rollback is a tested return to the last known policy and integration version. Keep the previous mapping, credentials reference, queue position, and configuration available. Do not delete unresolved jobs during a release.

Run a controlled rollback drill: switch the test workflow to the new version, process the fixed set, introduce a mapped failure, restore the previous version, and confirm that no address changes eligibility twice. Reconcile active jobs before and after the switch. If the provider continues a batch after rollback, quarantine its later results until they are evaluated under the intended policy.

Release only when the test manifest passes, exceptions have owners, suppression survives every path, evidence is complete, and rollback has been exercised. That is how verification becomes an accountable part of a system clients can understand and own.

Test Verification Against Your Campaign

We can map verification states, suppression rules, and release evidence to your real ICP and sending workflow during a free ICP and campaign-fit discovery call. Book your free ICP and campaign-fit discovery call →