Email validation API: a developer’s implementation guide

What an email validation API actually checks

“Email validation” describes several different operations. A browser can check whether a value resembles an address. A server can apply its supported syntax policy. DNS can provide evidence about the domain’s mail configuration. A specialist service may return mailbox-related evidence, risk signals and classifications. Your application then decides whether the result is sufficient for account registration, enrichment research or a CRM write.

These layers answer different questions. Syntax asks whether the input fits the supported address form. Domain checks ask whether relevant mail infrastructure can be discovered. Mailbox checking asks what the service could establish about a particular destination at a particular time. None proves that the address belongs to the intended person or that the person still works at the intended company.

RFC 5321, Simple Mail Transfer Protocol (October 2008), describes mail transport and domain routing. RFC 7505, A “Null MX” No Service Resource Record for Domains That Accept No Mail (June 2015), defines an explicit signal that a domain accepts no mail. Distinguish that signal from a missing MX record: the SMTP specification includes fallback behaviour. A simplistic “no MX means invalid” rule can reject addresses for the wrong reason.

If the question is how does email validation work, the practical answer is therefore a chain of checks with limits. Your acceptance policy should name the evidence required for the action. For registration, confirming control through a message serves a different purpose from predicting mailbox reachability. For enrichment, a discovered address also needs a current person-and-employer match. For outreach, consent, suppression and other applicable requirements remain separate controls.

Define the response before choosing a service

Start with three independent fields: input_state, check_state and action. For example, an address can be syntactically acceptable, have a timed-out remote check, and be held for later processing. Compressing those into valid: false would incorrectly make an infrastructure failure look like evidence against the address.

Do not lowercase the whole address as an undocumented convenience. RFC 5321 distinguishes the treatment of the local part from the domain. Likewise, removing dots or plus-tags globally can merge different addresses. Keep a display value, a provider-submitted value and any application comparison key separate. Document each transformation and test it against the address forms your product promises to support.

Internationalised addresses require an explicit support decision. A service may accept an internationalised domain while rejecting a non-ASCII local part. Do not describe either outcome as universal invalidity. State which formats your application and chosen provider support, and return a helpful correction or unsupported-format state rather than silently changing the address.

Validate email in JS for feedback, then validate again on the server

Browser validation improves feedback; it does not protect the API. HTML’s email input uses its own defined validity rules, and requests can arrive without your form. The WHATWG HTML Standard’s email-state definition is the relevant contract for the browser control. Treat the following JavaScript as a user-interface check only, not a mailbox test or a replacement for server validation.

<input id="work-email" type="email" required autocomplete="email">
<script>
const input = document.querySelector('#work-email');
function readEmail() {
  if (!input.reportValidity()) return null;
  return input.value.trim();
}
</script>

A single regular expression can look attractive when implementing browser validation. A large regex can become hard to maintain, impose unwanted format restrictions and still say nothing about the domain or mailbox. Prefer the native control for immediate form feedback and a documented server library or provider contract for the authoritative input policy. Do not send API credentials to the browser.

Keep the validation endpoint server-owned. Accept the address in a request body, impose an input-size limit, authenticate callers where appropriate, and restrict allowed destinations to configured provider endpoints. Never build a network destination from user-supplied input. Avoid putting raw email addresses into page URLs, analytics events, exception traces or ordinary access logs. A correlation ID usually supplies enough operational visibility.

Python: validate the address form before remote work

In Python, validate email input locally before requesting remote evidence. The following example uses the email-validator package’s documented API with deliverability checks disabled. It demonstrates local normalisation and explicit failure handling. Install and pin a reviewed package version in your own environment; this example does not include a remote validation provider or claim mailbox reachability.

from email_validator import validate_email, EmailNotValidError

def parse_candidate(raw):
    if not isinstance(raw, str) or len(raw) > 1024:
        return {"input_state": "rejected", "reason": "input_size_or_type"}
    try:
        result = validate_email(raw.strip(), check_deliverability=False)
    except EmailNotValidError:
        return {"input_state": "rejected", "reason": "unsupported_address_form"}
    return {
        "input_state": "accepted",
        "candidate": result.normalized,
        "check_state": "not_requested",
        "action": "await_remote_policy"
    }

The 1,024-character guard is an illustrative application request limit, not a statement of the maximum address length accepted by email standards. The library applies its own address rules. Notice that the example does not convert a parser success into deliverable: true. It also avoids returning the library’s raw exception to logs or analytics, where a message might expose input. Adapt supported formats and user-facing messages deliberately.

A production service should test ordinary business addresses, surrounding whitespace, Unicode inputs, empty values, malformed domains, oversized requests and inputs outside the supported format policy. Test the error mapping as carefully as the successful parse. A strict policy can be defensible for a particular workflow, but users need to know when the application does not support an address form rather than being told their mailbox does not exist.

Give remote checks a deadline and a bounded retry policy

Remote validation adds network and provider dependencies. Set a total application deadline as well as connection and response timeouts. Decide what the user sees when the deadline expires: pending, retry later or a restricted action. Do not keep a form spinner running until an unlimited retry loop eventually succeeds.

Record the provider’s original status alongside your normalised state. An HTTP success can still contain an unknown mailbox outcome. Conversely, a transport failure says nothing about the mailbox. For rate limits, follow documented retry guidance and any applicable Retry-After response. RFC 9110, HTTP Semantics (June 2022), defines that header; it is not permission to exceed your own deadline or usage budget.

Retry only failures that the provider documents as transient and that remain within your deadline. Use bounded exponential backoff with jitter, an attempt cap and a shared circuit breaker when failures are widespread. Authentication errors and unsupported input normally need correction, not repetition. A completed “not found” or rejected result should not be retried indefinitely just because it is commercially inconvenient.

A timeout can occur after the provider performed a chargeable check. Before retrying, understand its billing and idempotency contract. An application operation key prevents duplicate internal jobs, but it does not automatically stop a provider from billing repeated requests. Reconcile completed work and preserve unknown outcomes. If your system writes the result to a CRM, use a stable destination key and repeat-safe write logic separately from request deduplication.

Cache evidence without pretending it stays true forever

A cache reduces latency and repeated spend, but it is an evidence store with an expiry policy. Include the normalised address, provider, check type and policy version in the key or record. Store the provider’s evidence timestamp when available and the time your system received it. A new retrieval timestamp is not proof that the underlying mailbox was just reverified.

Use different handling for a transient failure and a completed result. A short cooldown can prevent repeated calls during an outage; it should not turn the failure into a durable “invalid address” classification. Equally, a historical positive result should not remain accepted after an employment change or a new bounce. Invalidate or re-evaluate when relevant evidence changes.

Deduplicate work carefully. The same address can appear on several CRM records because those records are duplicates, because a role mailbox is shared, or because identity mapping is wrong. One cached mailbox result can be reused under a documented policy, but that does not establish that every linked person owns it. Keep mailbox evidence separate from the person–company relationship.

Handle the cases that make a green badge misleading

A catch-all domain can make individual mailbox evidence uncertain. Preserve that state and apply an action-specific rule. A stale employer association can make an otherwise responsive address unsuitable for the intended contact. An ambiguous person match must remain unresolved even when an email service returns a positive technical result. Conflicting providers should trigger an evidence comparison, not a vote in which two identical claims automatically defeat one stronger source.

Missing fields deserve explicit treatment. If a response lacks its check time, method or supported status, your adapter must not manufacture the missing evidence. Unknown means unknown. For phone enrichment in the same workflow, do not let email acceptance approve an unverified number; number type, ownership and current reachability need their own rules. A returned business number is not automatically a mobile.

The existing email verification status guide covers how RevOps can interpret vendor labels. The implementation task here is different: preserve those labels faithfully across input handling, remote calls, caching and downstream writes. A technically tidy adapter is still wrong if it discards the uncertainty the provider actually returned.

Measure cost per accepted unique result, not API response

To decide how to check email validity at enterprise scale, measure the outcome your application needs. Count submitted unique addresses, locally rejected inputs, remote requests, billed attempts, completed checks, uncertain outcomes and policy-accepted unique results. Review a separate labelled sample for correctness. An acceptance rate is a policy outcome, not measured accuracy or an inbox-placement forecast.

Include provider charges, retry charges, engineering effort, review labour and incident handling in operating cost. Then divide by accepted unique results for a defined purpose. Do not compare one provider’s per-request price with another’s per-success price without normalising the denominator. Where the contract is unclear, ask what a timeout, duplicate, unknown response and partial result cost before running the pilot.

Measure latency at the point of decision, including local processing, queue time, remote calls and any destination write. Report percentiles and timeout share, not just an average that hides long waits. Segment results by input source and supported address class. A test containing only clean known addresses tells you little about malformed form submissions or conflicting enrichment candidates.

A release checklist for the validation adapter

• Define the action. State whether the result supports registration, research, CRM enrichment or another permitted use. Keep suppression and identity checks independent.
• Freeze an authorised test set. Include supported and unsupported address forms, known domains, uncertain outcomes and duplicates without publishing personal records.
• Test failures deliberately. Cover malformed responses, missing status fields, authentication failures, rate limits, DNS or provider timeouts and late callbacks.
• Prove bounded behaviour. Verify the total deadline, retry cap, concurrency limit, cooldown and maximum possible spend for the test cohort.
• Check data handling. Keep secrets server-side, restrict provider hosts, redact logs, apply access controls and document retention.
• Reconcile outcomes. Confirm unique completed jobs and destination writes; preserve pending work rather than silently dropping it.

TargetWise documents individual contact enrichment through REST and MCP, with work-email and business-phone results handled separately. Its current API documentation does not establish a standalone validation-only endpoint. Use it as a documented enrichment input to your own policy, and verify which evidence is actually returned. Do not promise that every email is freshly checked or that a returned address guarantees delivery. The documentation also warns against assuming repeated enrichment requests are free or idempotent.