POST /v1/validate

Validate a single email address through the 4-layer validation pipeline. The response also includes a combined-evidence assessment. It preserves the canonical result while explaining whether the strongest evidence came from SMTP, an exact delivery or bounce outcome, DNS only, or non-intrusive inference.

Endpoint

POST https://api.gtmapis.com/v1/validate

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-API-Key`	Yes	Your API key (`gtm_test_` or `gtm_live_`)
`Idempotency-Key`	No	Retry-safe key for one logical request. Successful responses are replayable for 24 hours without validating or charging again.

Retry-safe requests

Send a unique Idempotency-Key when a timeout or lost connection might cause your client to retry. Reusing the key with the same canonical email and contact context returns the exact successful JSON response and sets Idempotency-Replayed: true. The original response sets the header to false. A key reused with different request semantics returns 409 idempotency_key_conflict. A duplicate that is still running returns 409 idempotency_request_in_progress with Retry-After: 2. Only successful responses are retained, so insufficient-credit and transient failures can be retried with the same key after the cause is resolved.

Request Body

Field	Type	Required	Description
`email`	string	Yes	The string to classify as an email address; syntax-invalid strings return a normal free `invalid` result
`first_name`	string	No	Contact first name for non-intrusive combined-evidence scoring; must be supplied with `last_name`
`last_name`	string	No	Contact last name for non-intrusive combined-evidence scoring; must be supplied with `first_name`

Internationalized addresses

Unicode domain names are accepted and canonicalized to lowercase IDNA Punycode before syntax, DNS, cache, and SMTP processing. For example, Sales@BÜCHER.DE is processed and returned as Sales@xn--bcher-kva.de. Only the domain is case-normalized; the local part is preserved because SMTP local parts can be case-sensitive. RFC 6531 SMTPUTF8 dot-atom local parts are also accepted and preserved exactly. For example, üser@example.com continues through DNS and SMTP validation. The validator sends the internationalized recipient only after the selected MX advertises the RFC-required SMTPUTF8 and 8BITMIME capability pair; the required SMTPUTF8 and BODY=8BITMIME parameters are included on MAIL FROM. If no usable MX advertises the extension, the address returns 200 with result: "unknown", syntax_valid: true, smtp_status: "unknown_policy_or_inconclusive", unknown_reason_code: "smtp_smtputf8_unsupported", and zero credits charged. This is a server capability gap, not proof that the mailbox is invalid. Quoted local parts remain outside the supported syntax contract. A 400 is reserved for a malformed body or a missing/non-string email field.

Example Request

curl -X POST https://api.gtmapis.com/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -H "Idempotency-Key: contact-123-validation-v1" \
  -d '{"email":"john@company.com","first_name":"John","last_name":"Smith"}'

const response = await fetch('https://api.gtmapis.com/v1/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef',
    'Idempotency-Key': 'contact-123-validation-v1'
  },
  body: JSON.stringify({
    email: 'john@company.com',
    first_name: 'John',
    last_name: 'Smith'
  })
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.gtmapis.com/v1/validate',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef',
        'Idempotency-Key': 'contact-123-validation-v1'
    },
    json={
        'email': 'john@company.com',
        'first_name': 'John',
        'last_name': 'Smith'
    }
)

result = response.json()

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body := map[string]string{"email": "john@company.com"}
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.gtmapis.com/v1/validate", bytes.NewBuffer(jsonBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "gtm_test_1234567890abcdef1234567890abcdef")
    req.Header.Set("Idempotency-Key", "contact-123-validation-v1")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Response

Success Response (200 OK)

Valid Personal Email

{
  "email": "john@company.com",
  "result": "valid",
  "reason": "",
  "syntax_valid": true,
  "dns_valid": true,
  "dns_status": "valid",
  "smtp_valid": true,
  "smtp_status": "accepted",
  "unknown_reason_code": null,
  "validation_retry_action": "none",
  "domain_typo_suspected": false,
  "suggested_email": null,
  "is_role_based": false,
  "is_disposable": false,
  "is_catchall": false,
  "send_recommendation": "send",
  "pre_send_bounce_risk": "low",
  "pre_send_bounce_reason": "smtp_verified",
  "verification_method": "smtp",
  "combined_evidence_verdict": "verified",
  "combined_evidence_confidence": 1,
  "combined_evidence_action": "send",
  "combined_evidence_reason": "The recipient was accepted and the domain did not behave as catch-all.",
  "combined_evidence_shadow": false,
  "recovery_candidate_reason": null,
  "b2b_outbound_quality": "high",
  "b2b_quality": "high",
  "credits_charged": 1,
  "charge_reason": "Valid personal email with high B2B outbound quality"
}

Enterprise Gateway (Shadow Assessment)

Enterprise security gateways and some hosted mailbox providers intentionally conceal recipient existence. In that case SMTP remains inconclusive and the canonical result stays unknown. When contact context supports a non-intrusive assessment, the response exposes it separately:

{
  "email": "jane.doe@company.com",
  "result": "unknown",
  "syntax_valid": true,
  "dns_valid": true,
  "smtp_valid": null,
  "smtp_status": "unknown_provider_blocked",
  "unknown_reason_code": "smtp_security_gateway_blocked",
  "validation_retry_action": "manual_review",
  "is_catchall": null,
  "mx_security_gateway": true,
  "send_recommendation": "do_not_send",
  "pre_send_bounce_risk": "high",
  "pre_send_bounce_reason": "security_gateway_unverifiable",
  "verification_method": "combined_inference",
  "combined_evidence_verdict": "likely_deliverable",
  "combined_evidence_confidence": 0.78,
  "combined_evidence_action": "send_with_caution",
  "combined_evidence_reason": "mailbox hidden by enterprise security gateway; name-match strong; MX is a security gateway",
  "combined_evidence_shadow": true,
  "recovery_candidate_reason": "unknown_enterprise_gateway",
  "credits_charged": 0
}

While combined_evidence_shadow is true, continue to follow send_recommendation. Shadow assessments are persisted for prospective delivery and hard-bounce calibration; they do not change billing, cacheability, or the canonical result. unknown_reason_code is stable and intended for automation and aggregate reporting. charge_reason remains a human-readable explanation and may change without changing the underlying reason code. Temporary SMTP uncertainty is split by retry cause. Provider-requested deferral, recipient receiving limits, validation-route rate limits, and temporary sender policy blocks use validation_retry_action: "retry_later". Complete 451 4.3.0 Email server has temporarily rejected this message, 451 4.3.0 Mail server temporarily rejected message, 451 4.4.2 Timeout - closing connection, and 421 4.7.0 Try again later, closing connection replies use portable smtp_provider_retry_later semantics documented by Google and Proton. They remain non-suppressing, count against the destination circuit, and do not request an immediate retry. Wrong codes, statuses, incomplete diagnostics, token lookalikes, and layered enhanced statuses keep generic temporary behavior. The separate 451 4.3.0 Multiple destination domains diagnostic remains a protocol error. Google 421 4.7.0 Connection expired, try reconnecting remains generic temporary evidence and can request a new connection. Complete temporary RFC 3463 4.3.1 Mail system full, 4.4.1 No answer from host, 4.4.2 Bad connection, 4.4.3 Directory server failure, 4.4.4 Unable to route, 4.4.5 Mail system congestion, and 4.4.7 Delivery time expired replies also use smtp_provider_retry_later. These destination resource and routing failures remain non-suppressing, count against the destination circuit, and do not request an immediate same-route retry. The complete standardized diagnostic and a coherent temporary primary reply are required. Repeated RFC 2034 status lines are accepted only when every enhanced status agrees. Incomplete, lookalike, adjacent, reused, layered, and primary-class conflict evidence stays generic. Exact Microsoft 450 4.4.316 Connection refused [Message=Socket error code 10061] replies are also explicit temporary cases. The Microsoft reply uses smtp_provider_retry_later because Exchange Online has already failed its connection attempts to the external receiving server. It remains non-suppressing, counts against the destination circuit, and does not request an immediate same-route retry. The exact primary code, enhanced status, diagnostic, and a supported Microsoft-attributed MX are required. Exact Microsoft 550 4.4.7 QUEUE.Expired; message expired NDRs also use smtp_provider_retry_later. Exchange Online emits this permanent wrapper only after repeated delivery attempts exhaust the queue lifetime, so it remains temporary destination- transport evidence. It does not suppress the recipient or request an immediate same-route retry, but it counts against the destination circuit. Primary code 550, exact status 4.4.7, both diagnostic phrases, and a supported Microsoft-attributed MX are required; nearby or incomplete evidence stays inconclusive. Bare Microsoft 550 5.4.300 Message expired NDRs also use smtp_provider_retry_later when 5.4.300 is the sole enhanced status. They remain non-suppressing, count against the destination circuit, and do not request an immediate same-route retry. A nested downstream enhanced status makes this fallback abstain so the more specific cause remains available. Exact Google-attributed 454 4.7.0 login-limit replies and exact portable Google- and Proton-documented 454 4.7.0 Cannot authenticate due to a temporary system problem replies use temporary sender-policy evidence across SMTP phases. Exact Microsoft 4.7.26 IPv6 SPF/DKIM deferrals and Yahoo-attributed 421 or 451 temporary TS* deferrals with Message temporarily deferred, Messages from temporarily deferred, or All messages from will be temporarily deferred are validation- sender policy blocks. Yahoo TS and TSS tokens require exactly two digits. Yahoo assigns this family to sender complaints, content, reputation, or traffic patterns; Yahoo resource-unavailable replies remain destination retry-later evidence. These replies do not open the destination circuit or request an immediate same-route retry. Repair or wait for sender authentication or reputation before retrying. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and layered statuses keep generic temporary behavior. Google hostname lookalikes remain controls for the Google-only login-limit tuple. Exact Google- and Proton-documented 421 4.7.0 IP not in whitelist for RCPT domain, closing connection replies use smtp_sender_policy_temporary across SMTP phases and MX providers. They identify the validation sending route, not recipient or destination health, and use retry_later without suppression, destination-circuit impact, or an immediate same-route retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and layered statuses remain generic temporary evidence. Complete 450 4.2.1 and 550 5.2.1 replies that state the user is receiving mail or email too quickly, or at a rate that prevents additional messages, use smtp_recipient_rate_limited with retry_later across providers. Google and Proton both document this family as recipient receive pressure or delayed delivery. It does not suppress the recipient, open the destination circuit, or request an immediate retry. A plain 5.2.1, an inactive-account diagnostic, different recipient wording, a neighboring status, or a conflicting basic reply class keeps its standard or inconclusive meaning. Exact Proton 550 5.7.1 Email quota exceeded. replies on a Proton-owned MX use mailbox_temporarily_unavailable. Proton documents this provider-specific status as recipient mailbox capacity, not sender policy. The address is not permanently suppressed, the destination circuit stays closed, and no immediate same-route retry occurs. Retry after the recipient frees storage. The exact basic code, sole enhanced status, complete diagnostic, and Proton MX attribution are required. Wrong codes, incomplete or sender-scoped phrases, additional statuses, and Proton hostname lookalikes stay policy-scoped or inconclusive. Exact Proton-owned 550 permanent policy replies use the failed object to select an actionable cause. 5.7.0 Mail relay denied, unauthorized direct sending-IP, unauthenticated-domain, and 5.7.26 DMARC replies use smtp_sender_policy_rejected; 5.7.1 Invalid credentials for relay uses smtp_sender_identity_rejected; likely-unsolicited-message text uses smtp_message_content_rejected; and user-or-domain policy text uses smtp_provider_policy_rejected because the affected side is ambiguous. Each rule requires the complete Proton diagnostic, one enhanced status, basic code 550, and a Proton-owned MX. The DMARC form accepts one bounded valid domain token. All use manual_review and do not suppress the recipient, open the destination circuit, or request an immediate retry. Incomplete text, layered statuses, changed wording, and Proton hostname lookalikes stay generic. Permanent Microsoft 5.7.23 SPF and 5.7.25 IPv6 reverse-DNS failures use smtp_sender_policy_rejected with manual_review; they are not recipient rejection evidence. Exact Microsoft 5.1.8 Access denied, bad outbound sender replies also use smtp_sender_policy_rejected with manual_review. Microsoft assigns this reply to an account restricted for outbound spam, compromise, or sending limits. Investigate and secure the account, then remove its sending restriction before revalidating. The rule requires a coherent permanent basic reply, the exact status and diagnostic, and a supported Microsoft-attributed MX. It does not suppress the recipient, open the destination circuit, or request an immediate retry. Portable X.1.8 replies and incomplete or unattributed diagnostics keep their sender-identity behavior. Exact Microsoft 5.7.703 Tenant Allow/Block List replies, 5.7.705 sender-tenant threshold bans, and 5.7.708 sending-IP traffic blocks use the same cause. Microsoft assigns 5.7.703 to the sending organization’s block list even when the diagnostic names a recipient or domain, so it is not mailbox-absence evidence. These rules require a coherent permanent basic reply, the exact enhanced status, the complete documented diagnostic, and a supported Microsoft-attributed MX. Do not suppress the recipient, open the destination circuit, or request an immediate retry. Exact Microsoft 5.7.520 Access denied, Your organization does not allow external forwarding replies use smtp_provider_policy_rejected with manual_review. Microsoft assigns AS(7555) to an outbound spam policy that blocks automatic external forwarding. Review the forwarding rule and outbound spam policy before retrying. The rule requires a coherent permanent basic reply, the complete diagnostic including AS(7555), and a supported Microsoft-attributed MX. It does not suppress the recipient, open the destination circuit, or request an immediate retry. Incomplete diagnostics, neighboring statuses, different AS codes, class conflicts, and Microsoft hostname lookalikes stay generic. Exact Microsoft HVE 535 5.7.142, 5.7.143, and 5.7.144 XOAUTH2 failures use smtp_sender_identity_rejected. Exact HVE 550 5.2.240 and 5.2.241 sending-account setup or billing failures and 550 5.7.240 through 5.7.246 application, tenant, and external-sending restrictions use smtp_sender_policy_rejected. Recipient wording in the external-sending diagnostics describes the HVE sender account; it is not recipient-absence evidence. Microsoft 5.1.241 remains separate recipient evidence because it explicitly describes a send-only account with no mailbox. The HVE rules require the documented basic code, exact enhanced status, complete diagnostic, and a supported Microsoft-attributed MX. They use manual_review and never suppress the recipient, open the destination circuit, or request an immediate retry. Exact Microsoft 432 4.3.2 STOREDRV.Deliver; recipient thread limit exceeded replies use smtp_recipient_rate_limited with retry_later. They identify recipient mailbox processing pressure, not destination failure or recipient absence. The rule requires basic code 432, the exact enhanced status, the complete diagnostic, and a supported Microsoft-attributed MX. Wrong basic codes, neighboring statuses, incomplete diagnostics, and Microsoft hostname lookalikes stay generic temporary failures. The rule does not suppress the recipient, open the destination circuit, or request an immediate retry. Exact Microsoft HVE 421 4.3.240 authenticated-source connection limits use smtp_sender_rate_limited. Exact HVE 450 4.4.244 recipient-rate submission throttles use smtp_recipient_rate_limited. Both remain temporary with retry_later. They require the documented basic code, enhanced status, complete diagnostic, and a supported Microsoft-attributed MX. Neither suppresses a recipient, opens the destination circuit, or requests an immediate retry. Exact Proton-documented 421 4.7.0 Our system has detected an unusual rate of unsolicited mail originating from your IP address and 550 5.7.1 Our system has detected an unusual rate of unsolicited mail from your IP address replies use portable smtp_sender_rate_limited across SMTP phases and MX providers. The 421 reply remains unknown_temporary; the 550 wrapper remains unknown_policy_or_inconclusive. Both use retry_later and do not suppress the recipient, open the destination circuit, or request an immediate same-route retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and layered statuses keep their generic safe behavior. A permanent or statusless validation-sender quota uses smtp_sender_quota_exceeded with manual_review, because repeating the same request cannot repair operator-owned quota configuration. A temporary sender quota uses the same reason with retry_later. Exact Google 421 4.7.28 same-Message-ID quotas and exact Google- and Proton-documented 452 4.5.3 message recipient-count and domain-policy transaction-size limits use this cause without an immediate same-route retry. The 452 replies are portable across SMTP phases and MX providers. The exact 421 reply remains temporary and imported feedback remains soft. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and layered statuses keep their generic safe behavior. Exact 550 5.4.5 Daily sending quota exceeded, 550 5.4.5 Daily SMTP relay limit exceeded for user, and 550 5.7.1 daily SMTP relay customer-limit replies use the permanent portable form documented by Google and Proton. They do not suppress the recipient, open the destination circuit, or request an immediate retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, and mixed enhanced statuses stay generic. The complete 450 4.2.1 Peak SMTP relay limit exceeded for this customer. This is a temporary error. reply uses the portable temporary form documented by Google and Proton. It returns retry_later but does not suppress the recipient, open the destination circuit, or request an immediate retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, and mixed statuses keep their generic mailbox or temporary meaning. Exact Microsoft 4.5.3 Too many recipients replies also use this temporary cause with retry_later. Microsoft tells the sender to split envelope recipients into smaller transactions and resend. The rule requires a coherent temporary basic reply, the exact status and diagnostic, and a Microsoft-owned MX. It does not suppress the recipient, open the destination circuit, or request an immediate same-route retry. Exact Microsoft 5.7.232, 5.7.233, and 5.7.236 tenant external-recipient limits use this cause across SMTP phases. They do not suppress the recipient, open the destination circuit, or request an immediate retry. smtp_sender_identity_rejected also uses manual_review. It means the MX rejected the validation sender address, sender domain, HELO identity, or SMTP authentication principal; repair that sender configuration before revalidating the recipient. Complete Google- and Proton-documented SMTP authentication replies use this cause across MX providers. Shared tuples include 503 5.7.0 blocked identity-change and 554 5.7.0 excessive unauthenticated-command replies. Google tuples include 530 5.7.0 authentication-required, 534 5.7.14 and 534 5.7.90 browser-login, 534 5.7.90 application-password-required, 535 5.7.80 credential-rejection, and 504 5.7.40 unrecognized-authentication-type or unsupported-XOAUTH replies. Proton tuples include 530 5.5.1 authentication-required, 535 5.7.1 credential, application-password, or browser-login rejection, 535 5.5.4 unsupported AUTH-mode arguments, and 504 5.7.4 unrecognized-authentication-type replies. The exact Fastmail- and Yahoo-documented 535 5.7.8 Error: authentication failed: authentication failure reply also uses this cause across MX providers. Exact Fastmail-attributed 551 5.7.1 Not authorised to send from this header address uses the same cause only on a Fastmail-owned MX. Each rule requires the documented basic code, exactly one enhanced status, and the complete diagnostic. Both remain non-suppressing with manual review, no destination-circuit charge, and no immediate retry. Wrong basic codes, neighboring enhanced statuses, incomplete diagnostics, token lookalikes, and mixed enhanced statuses stay generic. The primary code keeps Google 550 5.7.40 DMARC policy under smtp_sender_policy_rejected. Exact Microsoft 5.7.57 client-authentication and 5.7.64 connector-attribution failures use this cause. Exact Microsoft 5.7.750 unregistered sender-domain failures also use this cause. Exact Microsoft 5.7.800 banned sender-domain replies instead use smtp_sender_policy_rejected. Exact Microsoft 5.7.124, 5.7.133, and 5.7.134 replies instead use mailbox_configuration_error because Microsoft assigns them to an existing recipient group or mailbox that rejects the sender class. Microsoft 5.7.12, 5.7.13, 5.7.135, and 5.7.136 extend this result to recipient organizations, public folders, and mail users configured to reject external senders. A non-conflicting permanent rejection during HELO or MAIL FROM receives this reason even when the reply text does not name the probe identity, because the server has not received RCPT TO and cannot be describing the recipient. When a pooled session is reused or a catch-all batch moves to its next recipient, an SMTP reply to RSET or the repeated MAIL FROM is preserved. Only a network failure can replace that session without returning the reply. If the error also reports incomplete MX consensus, a specific sender or protocol cause controls validation_retry_action. Incomplete consensus remains primary when a non-public route covers only one peer and other public MX evidence exists. SMTP protocol uncertainty is also explicit. smtp_tls_temporary uses retry_later. Certificate or protocol failure (smtp_tls_inconclusive), an inconclusive catch-all probe (smtp_catchall_probe_inconclusive), a positive reply that does not verify the recipient (smtp_recipient_unverified), and contradictory basic reply classes (smtp_reply_code_conflict) or enhanced status classes (smtp_enhanced_status_conflict) use manual_review. Complete 530 5.7.0 Must issue a STARTTLS command first replies use portable smtp_tls_inconclusive evidence documented by Google and Proton across SMTP phases, including MAIL FROM, because the diagnostic identifies the validation TLS exchange rather than the sender or recipient. They do not suppress the recipient, open the destination circuit, or request an immediate retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and mixed enhanced statuses stay generic. Exact Google- and Proton-documented 421 4.7.0 TLS required for RCPT domain, closing connection replies use the same portable cause with manual_review across SMTP phases and MX providers. They identify a destination transport requirement, not recipient or sender state, and do not suppress the recipient, open the destination circuit, or request an immediate same-route retry. Wrong basic codes, neighboring statuses, incomplete diagnostics, token lookalikes, and layered statuses remain generic temporary evidence. Exact Microsoft-attributed 450 4.4.317 Cannot connect to remote server [Message=UntrustedRoot] replies also use smtp_tls_inconclusive with manual_review. They identify a remote certificate-chain verification failure, not recipient state. Do not suppress the recipient, open the destination circuit, or request an immediate retry. Basic code 450, exact enhanced status 4.4.317, the complete diagnostic, and a supported Microsoft-attributed MX are required. Wrong basic codes, neighboring statuses, incomplete or different diagnostics, and Microsoft hostname lookalikes stay generic. Exact Microsoft-attributed temporary 4.4.8 MX hosts of <domain> failed MTA-STS validation and 4.7.5 Remote certificate failed MTA-STS validation. Reason: <validityStatus> replies also use smtp_tls_inconclusive with manual_review. They describe destination MTA-STS configuration, not recipient state. Do not suppress the recipient, open the destination circuit, or request an immediate retry. A coherent temporary basic reply, the exact enhanced status, the complete documented diagnostic, and a supported Microsoft-attributed MX are required. Conflicting primary reply classes, neighboring statuses, incomplete diagnostics, and Microsoft hostname lookalikes stay generic. Exact Microsoft 365-attributed temporary 4.7.321 through 4.7.325 destination STARTTLS, certificate, DANE, and DNSSEC replies also use smtp_tls_inconclusive with manual_review while they remain temporary unknowns. They describe destination transport-security configuration, not recipient state. Repair that destination configuration before revalidating. Do not suppress the recipient, open the destination circuit, or request an immediate retry. A coherent temporary basic reply, the exact enhanced status, the complete documented diagnostic, and a supported Microsoft-attributed MX are required. Incomplete diagnostics and conflicting primary reply classes stay generic. Exact Microsoft 365-attributed permanent 5.7.321 through 5.7.325 destination STARTTLS, certificate, DANE, and DNSSEC replies also use smtp_tls_inconclusive with manual_review. They describe destination transport-security configuration, not recipient state. Repair that destination configuration before revalidating. Do not suppress the recipient, open the destination circuit, or request an immediate retry. A coherent permanent basic reply, the exact enhanced status, the complete diagnostic, and a supported Microsoft-attributed MX are required. Incomplete diagnostics, wrong primary codes, and Microsoft hostname lookalikes stay generic. smtp_protocol_violation means an exact SMTP reply found an invalid validation command exchange. Complete 451 4.3.0 multi-domain transaction failures and 451 4.5.0 SMTP protocol violation replies use portable evidence documented by Google and Proton. Exact Proton-documented 454 4.5.0 STARTTLS pipelining and 454 5.5.1 STARTTLS may not be repeated replies use the same portable cause. Complete 502 5.5.1 unsupported-command and 503 5.5.1 command-order replies also use portable evidence documented by Google and Proton. The 451 and 454 families remain uncharged temporary unknowns; 502 and 503 remain uncharged policy or inconclusive unknowns. Separate destination domains before retrying the 4.3.0 case. Exact Google 501 and 555 5.5.2 syntax replies, 501 5.5.4 invalid or empty HELO/EHLO argument replies, 523 5.7.10 STARTTLS pipelining replies, 501 5.7.11 STARTTLS parameter replies remain uncharged policy or inconclusive unknowns. The exact provider rule overrides a generic phase-level sender-identity fallback. All use manual_review: inspect and repair the validator exchange before retrying. None suppresses the recipient, opens the destination circuit, or requests an immediate same-route retry. Wrong codes, statuses, incomplete diagnostics, token lookalikes, and mixed enhanced statuses keep generic behavior. The exact 454 5.5.1 tuple is the only portable exception to ordinary basic/enhanced class agreement. Google hostname lookalikes still keep the Google-only permanent command families generic. Exact class-coherent RFC 3463 permanent 5.5.1 Invalid command, 5.5.2 Syntax error, 5.5.4 Invalid command arguments, and 5.5.5 Wrong protocol version replies also use smtp_protocol_violation across SMTP phases. Exact 5.5.3 Too many recipients uses smtp_sender_quota_exceeded because it is an envelope transaction limit. All remain uncharged policy or inconclusive unknowns with manual_review; they do not suppress the recipient, open the destination circuit, or request an immediate retry. RFC 2034 multiline repetition is accepted only when all enhanced statuses agree. Temporary primary classes, undefined 5.5.0, incomplete diagnostics, token lookalikes, adjacent statuses, and mixed status layers keep their generic safe behavior. smtp_destination_capability_unsupported means an exact class-coherent RFC 3463 permanent 5.3.3 System not capable of selected features reply found a destination-system feature mismatch across SMTP phases. Review SMTP capability negotiation before retrying. The result remains an uncharged policy or inconclusive unknown; it does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. RFC 2034 multiline repetition is accepted only when every enhanced status agrees. Temporary primary classes, undefined 5.3.0, neighboring statuses, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. smtp_destination_configuration_error means an exact class-coherent RFC 3463 permanent 5.3.5 System incorrectly configured reply found destination mail configuration that cannot accept the message. Ask the destination administrator to repair the configuration before retrying. The result remains an uncharged policy or inconclusive unknown with manual review. It does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. Temporary primary classes, undefined or neighboring statuses, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. smtp_destination_routing_unavailable means an exact class-coherent RFC 3463 permanent 5.4.4 Unable to route reply found that the delivery system could not determine the next hop. Ask the destination or intermediate administrator to repair routing before retrying. The result remains an uncharged policy or inconclusive unknown with manual review. It does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. Temporary 4.4.4 remains delayed-retry evidence. Undefined or neighboring statuses, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. smtp_destination_system_not_accepting means an exact class-coherent RFC 3463 permanent 5.3.2 System not accepting network messages reply found that the destination mailbox host permanently refuses message intake. Ask the destination administrator to restore message acceptance before retrying. The result remains an uncharged policy or inconclusive unknown with manual review. It does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. Temporary 4.3.2 remains delayed-retry and destination-circuit evidence. Undefined or neighboring statuses, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. smtp_recipient_policy_rejected means an exact class-coherent RFC 3463 permanent 5.7.1 Delivery not authorized, message refused reply, or an exact Microsoft-attributed permanent 5.7.1 Delivery not authorized reply, was returned after RCPT TO. The reply identifies an authorization policy, but it does not prove that the recipient does not exist. Review sender or recipient allow-list policy, or ask the destination administrator before retrying. The result stays an uncharged policy or inconclusive unknown with manual review. It does not suppress the recipient, open the destination circuit, or request an immediate same-route retry. The shorter Microsoft form requires a supported Microsoft-attributed MX. Before RCPT TO, conflicting classes, neighboring statuses, incomplete diagnostics, MX or token lookalikes, longer phrase collisions, and mixed status layers keep their existing safe behavior. smtp_mailing_list_policy_rejected means an exact class-coherent RFC 3463 permanent 5.7.2 Mailing list expansion prohibited reply was returned after RCPT TO. The sender is not authorized to post to the intended mailing list. Review list posting permissions or ask the list administrator before retrying. The result remains an uncharged policy or inconclusive unknown with manual review. It does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. Replies before RCPT TO, temporary or conflicting classes, neighboring statuses, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. smtp_message_security_failure means an exact class-coherent permanent RFC 3463 5.7.3 through 5.7.7 diagnostic reported secure-message conversion, unsupported security features or algorithms, cryptographic processing, or message-integrity failure. Review message security features, keys, certificates, and algorithms before retrying. The result remains an uncharged policy or inconclusive unknown with manual review. It does not prove recipient absence, suppress the recipient, open the destination circuit, or request an immediate same-route retry. Temporary or conflicting classes, mismatched status/text pairs, incomplete diagnostics, token lookalikes, and mixed status layers keep their existing safe behavior. Exact provider-specific MTA-STS and SMTP authentication replies keep their narrower TLS or sender-identity causes. smtp_message_content_rejected means a coherent permanent RFC 3463 5.6.0 through 5.6.5 reply found a message-content, format, or media-conversion failure. This includes the exact Google 554 5.6.0 Email message is malformed reply. Exact Google 552 5.7.0 security-content or attachment replies and documented 550 5.7.1 invalid, missing, duplicate, multiple, encoded-word, Unicode, or malformed RFC 5322 header replies use the same cause only when a Google-owned MX and the complete diagnostic match. Exact Microsoft 550 5.0.350 oversized x-dg-ref Rich Text header and nested-attachment AS345 diagnostics use the same cause. Exact Microsoft 550 5.1.20 Multiple From addresses are not allowed without Sender address replies also use this cause. Exact Microsoft-attributed 550 5.6.11 Invalid characters replies use the same cause when the exact status, complete diagnostic, and supported Microsoft-attributed MX match. Microsoft assigns this failure to bare line feeds in the message, not recipient state. Repair the message, attachment, or sending program before revalidating. Wrong basic codes, neighboring statuses, incomplete or different diagnostics, and Microsoft hostname lookalikes stay generic. These rules require a supported Microsoft-attributed MX and the complete diagnostic; generic 5.0.350 stays generic. Exact Microsoft 5.7.512 Access denied, message must be RFC 5322 section 3.6.2 compliant replies use the same cause when a coherent permanent basic reply and supported Microsoft-attributed MX match. Microsoft assigns this diagnostic to a missing or invalid message From address, not recipient state. Exact Microsoft HVE 550 5.6.240 prohibited MIME-header and 550 5.6.241 missing or invalid mandatory From-header replies use the same cause when their complete diagnostics and a supported Microsoft-attributed MX match. These replies remain uncharged policy or inconclusive unknowns with manual_review. Review the message before retrying. They do not establish recipient absence, suppress the recipient, open the destination circuit, or request an immediate retry. A coherent temporary 4.6.5 Conversion failed reply remains an uncharged temporary unknown but uses smtp_message_content_rejected with manual_review. Repeated RFC 2034 status lines are accepted; incomplete or layered evidence stays generic. Successful 2.6.4 and unassigned 5.6.6 replies keep their generic behavior. Google hostname lookalikes, incomplete header diagnostics, and broad 5.7.1 policy replies also stay generic. smtp_message_too_large means a coherent permanent RFC 3463 5.2.3 per-mailbox message-length limit or 5.3.4 system message-size limit rejected the validation message. Google 552 5.3.4 message, attachment-count, and header-size replies use the same cause. It remains an uncharged policy or inconclusive unknown with manual_review. Reduce the message, attachments, or headers before retrying. The reply does not establish recipient absence, suppress the recipient, open the destination circuit, or request an immediate retry. Complete temporary 4.2.3 Message length exceeds administrative limit and 4.3.4 Message too big for system replies remain uncharged temporary unknowns but use smtp_message_too_large with manual_review. Repeated RFC 2034 status lines are accepted; incomplete, layered, and primary-class conflict evidence stays generic. Neighboring 5.3.3 also remains generic. smtp_routing_loop means a class-coherent RFC 3463 4.4.6 reply reported a persistent transient routing or forwarding loop, an exact Google 554 5.4.6 reply reported that the message exceeded 50 hops and may be in an email loop, an exact Proton-attributed 554 5.6.0 reply reported that the message exceeded 50 hops and may be in a mail loop, or an exact Microsoft 554 5.4.6 Hop count exceeded - possible mail loop or permanent 5xx 5.4.14 Hop count exceeded - possible mail loop ATTR34 reply reported a Microsoft routing loop. Portable 4.4.6 remains an uncharged temporary unknown with retry_later; every enhanced status must be 4.4.6, so compliant multiline repetition is accepted and layered statuses are rejected. The provider-specific permanent forms remain uncharged policy or inconclusive unknowns with manual_review. Review routing tables and user forwarding before retrying. The reply does not establish recipient absence, suppress the recipient, open the destination circuit, or request an immediate retry. Microsoft 5.4.6 requires primary code 554; Microsoft 5.4.14 requires a coherent permanent basic reply. Both require the complete diagnostic and a supported Microsoft-attributed MX. The Proton rule requires the complete diagnostic, only enhanced status 5.6.0, and a Proton-owned MX. Wrong codes, neighboring or layered statuses, incomplete diagnostics, token lookalikes, and provider hostname lookalikes keep generic behavior. Generic permanent 5.4.6 does not enter the portable rule. smtp_smtputf8_unsupported means the mailbox syntax is valid but the available MX path cannot verify an internationalized recipient. Its retry action is manual_review; repeatedly probing the same MX is not expected to add evidence. This cause remains primary when one equal-priority MX lacks complete SMTPUTF8 support and another peer supplies only negative recipient evidence. The result also retains incomplete-consensus evidence, but it does not become a generic automatic retry. smtp_ipv6_unsupported means the Microsoft MX accepted an IPv6 connection but the recipient domain does not accept email over IPv6. The API returns an uncharged unknown result with validation_retry_action: "manual_review". Use IPv4 SMTP egress before retrying; the response is not recipient rejection evidence and does not suppress the address. validation_retry_action is the bounded revalidation policy. Retry only when it is retry_later; route manual_review results to a human or provider-specific workflow instead of creating an automatic retry loop.

Role-Based Email (FREE)

{
  "email": "info@company.com",
  "result": "valid_role_based",
  "reason": "Role-based email address",
  "syntax_valid": true,
  "dns_valid": true,
  "dns_status": "valid",
  "smtp_valid": true,
  "smtp_status": "accepted",
  "domain_typo_suspected": false,
  "suggested_email": null,
  "is_role_based": true,
  "is_disposable": false,
  "role_type": "information",
  "send_recommendation": "send",
  "pre_send_bounce_risk": "low",
  "pre_send_bounce_reason": "role_based_but_verified",
  "b2b_outbound_quality": "low",
  "b2b_quality": "low",
  "credits_charged": 0,
  "charge_reason": "Role-based email - free for low B2B value"
}

Catch-All Domain (FREE)

{
  "email": "anyone@catchall.com",
  "result": "risky",
  "reason": "Catch-all domain detected",
  "syntax_valid": true,
  "dns_valid": true,
  "dns_status": "valid",
  "smtp_valid": true,
  "smtp_status": "accepted",
  "domain_typo_suspected": false,
  "suggested_email": null,
  "is_role_based": false,
  "is_disposable": false,
  "is_catchall": true,
  "catchall_confidence": "high",
  "send_recommendation": "review",
  "pre_send_bounce_risk": "medium",
  "pre_send_bounce_reason": "catch_all_domain",
  "b2b_outbound_quality": "none",
  "b2b_quality": "none",
  "credits_charged": 0,
  "charge_reason": "Catch-all domain - cannot verify individual mailbox"
}

Invalid Email (FREE)

{
  "email": "notreal@fakeemail123.com",
  "result": "invalid",
  "reason": "Domain has no MX records",
  "syntax_valid": true,
  "dns_valid": false,
  "dns_status": "invalid_no_mail_route",
  "smtp_valid": null,
  "smtp_status": "not_checked",
  "is_catchall": null,
  "domain_typo_suspected": false,
  "suggested_email": null,
  "validation_layer": "dns",
  "send_recommendation": "do_not_send",
  "pre_send_bounce_risk": "blocked",
  "pre_send_bounce_reason": "invalid_dns_or_no_mail_domain",
  "b2b_outbound_quality": "none",
  "b2b_quality": "none",
  "credits_charged": 0,
  "charge_reason": "Invalid email does not consume credits"
}

Invalid Syntax (FREE)

{
  "email": "not-an-email",
  "result": "invalid",
  "syntax_valid": false,
  "dns_valid": false,
  "dns_status": "not_checked",
  "smtp_valid": null,
  "smtp_status": "not_checked",
  "unknown_reason_code": null,
  "validation_retry_action": "none",
  "verification_method": "syntax_only",
  "send_recommendation": "do_not_send",
  "pre_send_bounce_risk": "blocked",
  "pre_send_bounce_reason": "invalid_syntax",
  "credits_charged": 0,
  "charge_reason": "Invalid email syntax - no credit charged"
}

Consumer Domain Typo (FREE)

{
  "email": "john@gmial.com",
  "result": "invalid",
  "reason": "Domain has no MX records",
  "syntax_valid": true,
  "dns_valid": false,
  "dns_status": "invalid_no_mail_route",
  "smtp_valid": null,
  "smtp_status": "not_checked",
  "is_catchall": null,
  "domain_typo_suspected": true,
  "suggested_email": "john@gmail.com",
  "send_recommendation": "do_not_send",
  "pre_send_bounce_risk": "blocked",
  "pre_send_bounce_reason": "invalid_dns_or_no_mail_domain",
  "credits_charged": 0
}

The correction is advisory and never upgrades the original result. Validate suggested_email as a new address before sending.

Unknown Verification (FREE)

{
  "email": "john@restrictive.com",
  "result": "unknown",
  "reason": "SMTP verification not permitted",
  "syntax_valid": true,
  "dns_valid": true,
  "dns_status": "valid",
  "smtp_valid": null,
  "smtp_status": "unknown_policy_or_inconclusive",
  "is_catchall": null,
  "smtp_response": "550 5.7.1 Recipient verification not allowed",
  "send_recommendation": "unverified",
  "pre_send_bounce_risk": "medium",
  "pre_send_bounce_reason": "mailbox_unverified_unknown",
  "b2b_outbound_quality": "unknown",
  "b2b_quality": "unknown",
  "credits_charged": 0,
  "charge_reason": "Unable to verify - no credit charged"
}

Response Fields

string

required

The validated email address. Internationalized domains are returned as lowercase IDNA Punycode; the local part is preserved.

string

required

Validation result: valid, valid_role_based, risky, invalid, or unknownSee Result Categories for details

string

Human-readable explanation of the validation result

string

required

Stable DNS evidence: valid, valid_delivery_evidence, invalid_null_mx, invalid_no_mail_route, unknown_misconfigured, unknown_temporary, unknown_budget_blocked, or not_checked. Treat invalid_* as permanent no-mail evidence. Treat unknown_* as inconclusive, follow validation_retry_action to distinguish transient failures from cases that need review, and do not send until validation policy permits it.

string

required

Revalidation policy: none, retry_later, or manual_review. Schedule an automatic retry only for retry_later.

string

required

Action to apply before sending: send, review, unverified, or do_not_send. Follow this field instead of treating smtp_valid=true as a delivery guarantee.

string

required

Final bounce-risk level: low, medium, high, or blocked. This combines raw validation with tenant suppression, recent delivery, and statistically gated domain/provider outcome evidence.

string

required

Stable machine-readable reason for the risk decision. For example, smtp_acceptance_outcome_risk means the MX accepted the probe but prospective outcomes show elevated hard-bounce risk. recipient_opt_out_suppression means this tenant previously received an unsubscribe or complaint and no provider validation was performed. dns_inconclusive means DNS was temporary, malformed, or unavailable; retry it rather than treating the domain as permanently invalid. mixed_mx_topology_unverifiable means equally preferred MX routes span provider families, so no single SMTP probe represents the domain’s real delivery path; the result is uncharged and held from sending. smtp_acceptance_risk_unavailable means raw SMTP accepted the recipient, but outcome-risk calibration could not complete; retry before sending. delivery_evidence_check_unavailable means a negative provider result could not be compared with recent tenant-observed delivery; retry before treating the address as invalid or risky.

boolean | null

required

true means the remote MX accepted the SMTP recipient probe, false means it did not accept the current recipient transaction, and null means no mailbox verdict was established. Use smtp_status to distinguish a permanent mailbox rejection from temporary unavailability. This is raw evidence, not a promise of final delivery; use the recommendation and risk fields for sending policy.

string

required

Stable SMTP evidence: accepted, accepted_delivery_evidence, rejected_mailbox, rejected_domain, rejected_prior_hard_bounce, mailbox_configuration_error, mailbox_temporarily_unavailable, unknown_temporary, unknown_policy_or_inconclusive, unknown_transport, unknown_budget_blocked, unknown_provider_blocked, or not_checked. rejected_mailbox includes exact Yahoo, Yahoo Japan, and AOL 554 delivery error: dd This user doesn't have a <provider> account replies on a Yahoo-owned MX when no enhanced status is present. Wrong or missing basic codes, added enhanced statuses, and Yahoo MX lookalikes stay inconclusive. rejected_domain records unanimous domain-scoped negative evidence from the decisive equal-priority MX peers, including RFC 7504 556 or RFC 7505 enhanced status 5.1.10 (recipient domain has Null MX), or RFC 7504 521 from every advertised MX host. If one decisive peer returns a mailbox-specific rejection, the unanimous negative result remains rejected_mailbox and DNS stays valid. A single 521 is host-scoped; alternate MX hosts are tried before the domain is rejected. mailbox_configuration_error is standardized RFC 3463 5.2.4 mailing-list evidence or exact provider-attributed recipient configuration evidence. Hold the address from sending and route it to manual review because the list owner, recipient, or email administrator must repair it. mailbox_temporarily_unavailable includes exact Yahoo Japan 554 delivery error: dd mailbox quota is overlimit replies on a Yahoo-owned MX when no enhanced status is present, and exact Proton 550 5.7.1 Email quota exceeded. replies on a Proton-owned MX. Retry after the recipient frees storage; do not permanently suppress the address. A generic 5.7.1 remains policy evidence. Replies before RCPT TO never establish recipient validity. An ordinary 4xx greeting, HELO, or MAIL FROM reply returns unknown_temporary; a 5xx reply at those stages returns unknown_policy_or_inconclusive, even if its text resembles a mailbox rejection. A non-conflicting permanent HELO or MAIL FROM rejection uses smtp_sender_identity_rejected because it rejects the validation probe identity before the server receives a recipient. Pooled reuse and multi-recipient probing preserve every structured RSET or repeated MAIL FROM reply. Only a network failure can replace the session without returning that evidence. A specific nested sender or protocol cause controls the retry action instead of the generic incomplete-consensus wrapper. A non-public peer remains incomplete consensus when public MX evidence exists. When an MX advertises STARTTLS, validation negotiates verified TLS and sends a fresh EHLO before MAIL FROM and RCPT TO. A temporary STARTTLS failure is unknown_temporary; certificate or protocol verification failure is unknown_policy_or_inconclusive. Validation never disables certificate checks or silently downgrades after a failed TLS handshake. A full/disabled mailbox is unavailable—not nonexistent—and should be retried later. Raw accepted evidence can still be catch-all or outcome-downgraded; always follow the final recommendation and bounce-risk fields. MX routes are tried in ascending DNS preference. A backup MX is used only after a transport failure; an SMTP policy, reputation, mailbox, or recipient response from a reachable preferred server is never bypassed by rotating to another MX. For up to four unique equally preferred MX peers, every reachable peer must return the same decisive recipient verdict. Conflicting verdicts return pre_send_bounce_reason=mx_recipient_verdict_conflict; a partially unreachable tier returns mx_consensus_incomplete. Both are uncharged, high-risk, and do_not_send rather than valid or invalid.

string

Detected provider for the authoritative preferred MX tier. Mixed MX Routing means equally preferred routes span known provider families or combine a known provider with an unclassified route. That topology returns smtp_status=unknown_provider_blocked rather than treating one arbitrarily ordered MX response as mailbox proof.

string

Bounded provenance for the decision, such as validation_engine, recent_delivery_evidence, or a suppression/outcome evidence path. Use this field for audit and explanation; continue to automate from send_recommendation, pre_send_bounce_risk, and validation_retry_action.

boolean

true when the preferred MX path is a recognized enterprise security gateway that may conceal mailbox existence. This explains an inconclusive mailbox result; it does not mean the address was verified.

boolean

required

true only when DNS is invalid and the supplied domain is a unique one-edit misspelling of a bounded major consumer mailbox provider. It never changes the original result, recommendation, or charge.

string | null

required

A possible corrected consumer address, or null. Treat this as user-facing input repair and validate the suggestion separately before sending.

boolean

required

true if the email is a generic business inbox (info@, support@, etc.)

boolean

required

true when the domain is a known temporary/disposable mailbox provider. Disposable addresses return risky, are not called invalid, and consume no validation credit.

boolean

true if the domain is a free email provider (Gmail, Yahoo, Outlook, etc.)

boolean | null

required

true means random-recipient probes established catch-all behavior, false means they established non-catch-all behavior, and null means catch-all behavior was not measured.

number | string | null

Confidence is either a numeric probability from 0 through 1, a legacy level of high, medium, or low, or null when catch-all confidence was not measured. The field may also be omitted.

string

required

B2B outbound value: high (worth using), low (role-based), none (invalid/risky), or unknownSee B2B Quality Scoring for details

integer

required

Number of credits charged: 0 (free) or 1 (charged)Only valid personal emails with b2b_outbound_quality: "high" are charged

string

required

Explanation of why credits were or weren’t charged

string

Category of role-based email (e.g., “information”, “support”, “sales”)Only present if is_role_based is true

string

Layer where validation stopped: syntax, dns, smtp, or catchallUseful for debugging failures

string

Raw SMTP server response (when applicable)Useful for understanding SMTP-level issues

Error Responses

400 Bad Request

{
  "error": "Bad Request",
  "message": "Email field is required"
}

Common causes:

Missing email field
Empty email string
Malformed JSON

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Common causes:

Missing X-API-Key header
Invalid or revoked API key
Incorrect API key format

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 10000 requests per minute",
  "retry_after": 60
}

Solution: Wait for the retry_after seconds before making more requests

502 Upstream Validation Failure

{
  "error": "Validation failed. Please try again.",
  "code": "validation_upstream_failed",
  "retry_after": 30
}

Wait for the Retry-After header or retry_after body value before retrying. The failed validation does not consume a credit.

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Solution: Retry the request or contact support if the issue persists

Performance

Cached DNS: ~50ms average
Uncached DNS: ~500ms average
Full SMTP validation: ~2s average

Best Practices

Error Handling

Always handle all possible result types:

const result = await validateEmail('john@company.com');

switch (result.result) {
  case 'valid':
    // High-value email - use in campaigns
    if (result.b2b_outbound_quality === 'high') {
      addToCampaign(result.email);
    }
    break;

  case 'valid_role_based':
    // Low-value email - use with caution
    addToSecondaryList(result.email);
    break;

  case 'risky':
    // Catch-all - avoid in campaigns
    markAsRisky(result.email);
    break;

  case 'invalid':
    // Remove from list
    removeFromList(result.email);
    break;

  case 'unknown':
    // Can't verify - test carefully
    addToTestList(result.email);
    break;
}

Rate Limiting

For high-volume validation, use the bulk endpoint:

// Instead of this (1000 requests)
for (const email of emails) {
  await validateEmail(email);  // ❌ Slow, hits rate limit
}

// Do this (10 requests for 1000 emails)
const chunks = chunkArray(emails, 100);
for (const chunk of chunks) {
  await validateBulk(chunk);  // ✅ Fast, under rate limit
}

Validation

Account

Monitoring

Validate Single Email

POST /v1/validate

Endpoint

Headers

Retry-safe requests

Request Body

Internationalized addresses

Example Request

Response

Success Response (200 OK)

Valid Personal Email

Enterprise Gateway (Shadow Assessment)

Role-Based Email (FREE)

Catch-All Domain (FREE)

Invalid Email (FREE)

Invalid Syntax (FREE)

Consumer Domain Typo (FREE)

Unknown Verification (FREE)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

502 Upstream Validation Failure

500 Internal Server Error

Performance

Best Practices

Error Handling

Rate Limiting

Next Steps

Bulk Validation

Result Categories

​POST /v1/validate

​Endpoint

​Headers

​Retry-safe requests

​Request Body

​Internationalized addresses

​Example Request

​Response

​Success Response (200 OK)

​Valid Personal Email

​Enterprise Gateway (Shadow Assessment)

​Role-Based Email (FREE)

​Catch-All Domain (FREE)

​Invalid Email (FREE)

​Invalid Syntax (FREE)

​Consumer Domain Typo (FREE)

​Unknown Verification (FREE)

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​502 Upstream Validation Failure

​500 Internal Server Error

​Performance

​Best Practices

​Error Handling

​Rate Limiting

​Next Steps

Bulk Validation

Result Categories

POST /v1/validate

Endpoint

Headers

Retry-safe requests

Request Body

Internationalized addresses

Example Request

Response

Success Response (200 OK)

Valid Personal Email

Enterprise Gateway (Shadow Assessment)

Role-Based Email (FREE)

Catch-All Domain (FREE)

Invalid Email (FREE)

Invalid Syntax (FREE)

Consumer Domain Typo (FREE)

Unknown Verification (FREE)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

502 Upstream Validation Failure

500 Internal Server Error

Performance

Best Practices

Error Handling

Rate Limiting

Next Steps