Email Verifier Migration Checklist: Moving From ZeroBounce, NeverBounce, Hunter or Another Tool

Migrate an email verifier as a data-contract change, not a credential swap. Export the old evidence, define neutral business outcomes, map both providers into that model, run a representative parallel sample, and keep a rollback path until production behavior is stable. This protects CRM history and prevents a change in status vocabulary from silently changing who receives mail.

The process applies when moving from ZeroBounce, NeverBounce, Hunter, Bouncify, Mail Verifier, Mailboxlayer, or another service. Product contracts change, so verify each provider's current documentation and account behavior directly. This checklist does not assert competitor features, pricing, limits, or quality.

Inventory every dependency

Search beyond the obvious API client. Verification can affect signup forms, batch jobs, CRM fields, automation filters, dashboards, alerts, exports, data warehouse models, billing, and support procedures.

• Single-address and bulk endpoints.
• API keys, secrets, scopes, and secret-rotation process.
• Request fields, file formats, and maximum job rules.
• Response statuses, flags, reasons, scores, and timestamps.
• Polling, callbacks, webhooks, scheduled jobs, and queues.
• Retry, timeout, rate-limit, and caching behavior.
• CRM and marketing-platform properties.
• Suppression, consent, review, and manual-override logic.
• Reports, alerts, support macros, and audit retention.

Assign an owner and test case to each dependency. A migration is not complete when the new call succeeds; it is complete when downstream decisions still mean what the organization approved.

Export old results before access changes

Export the evidence permitted by the current account before cancelling or rotating anything. Preserve the original address, provider status, sub-status or reason, flags, score definition, check time, request or job identifier, verification mode, and source record ID where available.

Record the provider, API or export version, export time, filters, and column definitions. Keep raw history read-only. Do not edit old status names to look like new statuses, since that destroys the evidence needed to explain disagreements later.

Create a provider-neutral decision model

Do not map one provider's “valid” directly onto another provider's nearest-looking word. First define the business actions your systems actually need:

• Eligible after consent and suppression checks.
• Restricted to a named purpose.
• Review because evidence is risky or conflicting.
• Retry because a condition is temporary.
• Suppress the address because evidence is conclusive.
• Pending because the job is incomplete.

Then map each native status and flag into this intermediate model with an explanation. Preserve both native result and derived action. This avoids treating different provider definitions as interchangeable.

Map Mailthentic's result model explicitly

Mailthentic exposes user-facing valid, risky, invalid, and unknown buckets, with more specific stored statuses. Deliverable statuses include confirmed and unconfirmed variants. Risky statuses include catch-all and missing-authentication variants. Invalid statuses include syntax, domain, and no-MX failures. Disposable and role are flags, not standalone stored statuses.

Before writing the translation table, review the Mailthentic status meanings and the existing API integration guide. Map documented semantics rather than matching labels by appearance.

Serialized results can include status, reason, confidence_score, confidence_breakdown, syntax, DNS, MX, provider, SMTP, mailbox, catch-all, authentication, flags, verification-mode fields, campaign readiness, and created_at. Clients must tolerate additive fields. Do not invent fields such as valid, risk_level, provider, or checked_at when consuming the native response.

Compare valid and invalid definitions with test records

Write a mapping worksheet with one row per old native state and one row per new native state. Add the documented meaning, available evidence, business action, retry eligibility, and unresolved question. Pay special attention to:

• Whether syntax and domain failures have distinct values.
• How unconfirmed but usable-looking addresses are represented.
• Whether disposable and role are statuses, flags, or reasons.
• How catch-all behavior affects the main status.
• What unknown includes and when retry can help.
• What a confidence or quality score actually claims.

Never compare score numbers without comparing their definitions. Mailthentic's confidence score expresses confidence in available evidence. It is not a measured inbox probability.

Preserve catch-all and unknown differences

Catch-all is a common migration trap. One provider may use a dedicated state, another may use a flag, and a third may group the evidence under unknown or accept-all language. Your intermediate model should preserve the original representation and apply one approved review policy.

Unknown also needs subgroups. Separate temporary connection or DNS conditions from provider ambiguity and from a job that has not completed. Otherwise the migration can retry permanent ambiguity forever or suppress records after a short outage.

Test duplicate handling at each layer

Document whether the old workflow billed, returned, or collapsed duplicates and how your own code joined results back to source rows. Mailthentic's bulk workflow processes unique normalized addresses once per job. That does not mean a CRM should merge every record sharing an address.

Create fixtures with whitespace, case variation, repeated records, shared role inboxes, blank values, and corrected addresses. Confirm input counts, unique checks, returned rows, source joins, and billing expectations using current account evidence.

Change API authentication safely

Mailthentic accepts Authorization: Bearer mt_... as the preferred API-key form and also supports X-API-Key. Keys are stored as hashes and can carry scopes. External API-key callers require paid status and the appropriate scope.

1. Create a least-privilege key through the approved account process.
2. Store it in the deployment secret manager, not code or browser storage.
3. Deploy configuration without routing production traffic yet.
4. Test authentication using GET /api/me, which does not create a verification.
5. Verify 401, 402, and 403 paths in a safe environment.
6. Rotate or revoke the old key only after rollback no longer depends on it.

Update endpoints and asynchronous control flow

Mailthentic single verification uses POST /api/verify/single with JSON containing one email. An accepted request spends one credit and returns HTTP 202 with job_id, status_url, and results_url. The client polls the returned URLs. Bulk uses POST /api/verify/bulk with a CSV or XLSX multipart file and is also asynchronous.

Do not wrap this contract in a synchronous assumption. Store pending state, use server-side request timeouts, and separate submission from result handling. Update mocks and tests to reflect 202 acceptance rather than a completed result.

Review rate limits, errors, and retries

The public Mailthentic API contract does not promise a fixed requests-per-second number. The application has configurable controls, job limits, and concurrency rules. Design clients to handle 429 and its returned message, plus 400, 401, 402, 403, 413, transient 5xx, timeouts, and connection failures.

Compare the old integration's retry assumptions with the new error contract. Retry only transient conditions using exponential backoff and jitter. Do not retry malformed input, invalid credentials, missing scope, or insufficient credits without an external change. Prevent a response timeout from creating duplicate jobs blindly.

Audit webhooks, callbacks, and polling

Inventory any old webhook signature validation, callback URL, event type, retry schedule, and dead-letter process. Do not assume the replacement offers an identical callback. The verified Mailthentic single contract provides polling URLs. If your architecture previously waited for a webhook, add a poller or internal job coordinator and test recovery after a worker restart.

Use stable internal correlation IDs between source records and submitted jobs. Store the provider job ID separately. Log state transitions without placing raw email addresses or API keys in broad logs.

Update CRM and automation fields

Keep historical provider fields read-only and create versioned Mailthentic fields or a provider-neutral result object. Update filters, scoring, lists, dashboards, and automations together. A renamed field that is not added to a workflow can silently route every record down a default branch.

For native CRM availability, rely on the current integration hub and database status. Implemented provider code does not mean every published integration is live in every environment. File export and re-import remains the safe fallback.

Run a representative parallel sample

Select permission-based test records across real sources and expected edge cases: syntax failure, bad domain, deliverable evidence, catch-all, disposable, role, free provider, protected provider, temporary response, unknown, and duplicates. Include records that affected important business decisions, but protect personal data.

Run both providers close enough in time to reduce natural change. Compare native evidence first, then compare the derived business decision. Do not call every difference an error. Receiving systems change, provider methods differ, and uncertainty can be represented honestly in several ways.

Sample disagreements manually

Stratify disagreements by source and reason. Review the full evidence, documentation, time gap, and later permitted outcomes. Avoid sending test campaigns solely to adjudicate addresses without a valid communication purpose. Do not use a small sample to publish a universal accuracy claim.

Update the mapping only when a repeatable semantic difference is understood. Preserve exceptions in a review queue rather than bending every status into a binary result.

Prepare rollback and cutover

Cut over a small percentage or one source first. Freeze unrelated mapping changes. Keep the old result history, code path, and credentials only for the approved rollback window, then remove access and secrets under normal change control.

Final cutover checklist

1. Dependency inventory is complete and owned.
2. Old results and schemas are archived under retention policy.
3. Native-to-neutral mappings are reviewed.
4. Catch-all, unknown, disposable, role, and duplicate cases are tested.
5. Authentication, scopes, secrets, endpoints, and polling are deployed.
6. Error and retry paths are tested, including insufficient credits and 429.
7. CRM fields, filters, automations, dashboards, and support guidance are updated.
8. Parallel results and a sample of disagreements are reviewed.
9. Rollback is rehearsed and the decision owner is available.
10. Old credentials are revoked after the observation window.

Use the tool comparison for broad selection context and the ZeroBounce alternative page where that specific evaluation applies. Confirm current commercial terms on pricing rather than copying them into migration code.