JSON Schema for Email Validation Failure Details in Real-Time Verification

Why Real-Time Email Verification Needs Detailed Failure Feedback

You send an email campaign. Some bounce. You check your list. The error says “invalid.” That’s it. No context. No reason. Just a dead end.

Real-time email verification isn’t just about marking addresses as valid or invalid. It fails for dozens of nuanced reasons — a catch-all domain, a temporary greylist, a blocked role account, or a malformed address that’s syntactically correct but never receives mail. Without structured failure details, diagnosing why an email failed becomes a guessing game.

A standardized JSON schema for email validation failure details turns vague errors into actionable insight. It lets systems parse, route, and resolve issues automatically — not just flag them.

Key takeaways

• Failure details in a consistent JSON schema enable automated handling of validation results across systems, reducing manual排查.
• Real-time verification without granular failure feedback leaves senders blind to deliverability risks like catch-all domains, role accounts, or greylisting.
• Standardized schema integration supports precise error categorization — valid, invalid, risky, catch-all, temporary, role, disposable — and enables data-driven list hygiene.

What Is the Standard JSON Schema for Email Validation Failure Details?

You’re looking for a consistent, machine-readable format that tells you exactly why an email failed verification. The standard JSON schema includes fields like status, verdict, failure_reason, detailed_code, timestamp, and optionally suggestions. These fields map directly to stages in the validation flow—from basic syntax checks to SMTP handshake results—so you can act on failures with precision.

The Role of Each Field in the Validation Workflow

Let’s break down what each field does. status is a high-level indicator: valid, invalid, or catch-all. verdict refines that, telling you whether the failure was due to syntax, domain, or delivery issues—like "role account" or "disposable email".

failure_reason gives a human-readable explanation: "Domain not found" or "Email service is temporarily unavailable". It’s designed to be clear even if you’re not a developer. detailed_code is the technical counterpart—think 550 from SMTP or dns_mx_unavailable—it’s what you use for automation, error tracking, or debugging.

Timestamps ensure you know when the check happened, which matters for rate-limiting or retry logic. And suggestions (when present) might recommend actions like checking for typos or verifying with a deliverability test. It’s not always included, but when it is, it reduces guesswork.

Why This Structure Matters in Practice

Without a predictable schema, your automation tools can’t interpret results consistently. You might misclassify a 550 error as a syntax issue when it’s actually a greylisting delay. That leads to wasted sends, bad list hygiene, and damaged sender reputation.

Industry tools like SendGrid and Mailgun use similar patterns, and it’s no accident—the structure aligns with SMTP and RFC guidelines for error codes. You can see how protocols layer across RFC 5321 (SMTP) and RFC 5322 (email format), ensuring interoperability.

With Emaillistchecker.io’s real-time verification API, you get this same structured output on every call—consistent, accurate, and ready for integration into your workflow. Whether you’re cleaning a list before sending or building a signup validation layer, having a standard schema means fewer surprises and faster fixes.

How Emaillistchecker.io Returns Failure Details in Real-Time Verification

When you verify an email via our real-time API, the response includes a structured failures object nested inside verification_result, giving you immediate, predictable insight into why an email failed. Each failure includes a code, a reason, and a readable description, so you can act on the cause—whether it’s a syntax issue, invalid domain, or non-existent mailbox. This consistent JSON schema lets you automate rejection workflows without guesswork.

The Predictable Shape of Failure Data

Let’s say an email fails during verification. The API response surface is clean: verification_result.failures returns an array where each item has details: { reason, code, description }. For example, reason: "syntax_error" with code: 101 and description: "Invalid local part format". These codes are stable—101 always means syntax failure in the local part, 102 means invalid domain syntax, and so on. You can rely on them in logic, logs, or integrations.

This structure is not arbitrary. It aligns with standards like RFC 5321 for SMTP and RFC 5322 for email address syntax. We don’t invent meanings—each code corresponds to a known, documented category of failure. For instance, a code: 203 means the domain exists but the mailbox doesn’t, while code: 301 signals a catch-all configuration. This clarity helps you filter, categorize, and clean your list at scale.

Real-world cases often involve misused email forms. Maybe a user typed john@company. or admin@localhost. Our API flags these with code: 101, not just “invalid.” That’s because syntax errors in local or domain parts are the primary source of premature bounces. According to Return Path data, about 40% of email delivery failures originate from malformed addresses before even reaching a mail server.

Use It in Your Workflow

Whether you’re building a signup flow or cleaning a 50,000-recipient list, this level of detail turns verification from a binary “valid/invalid” check into an actionable audit trail. You can filter failures by code to prioritize fixes (e.g., fix syntax before checking deliverability), or feed the output directly into downstream systems like CRM or email service providers.

See how it fits into your stack. Use our verification API to test real-time responses, or run bulk jobs with bulk verification. You’ll get the same structured output—no exceptions, no missing data.

Key Fields in a Real-Time Verification Failure JSON Schema

You need a real-time email validation failure schema that surfaces the exact reason an email failed—down to machine-readable codes and actionable fixes. The core fields include status (failed/rejected), verdict (invalid, catch-all, risky, disposable, blocked), failure_reason (e.g. smtp_timeout), detailed_code (for debugging), timestamp (ISO 8601), and optional suggestions with repair steps. These fields let you automate remediation and track deliverability at scale. For reference, the SMTP RFC 5321 defines standard response codes that many services use internally to classify failures.

Understanding the Field Roles

Let’s break down what each field does in practice. The status field is binary: failed or rejected. It’s the final verdict. The verdict tells you why it failed—this is the user-facing label. For example, a catch-all means the domain accepts any email, which signals spam risk. A disposable verdict indicates a temporary email service, common with tools like Mailinator or TempMail. These are actionable flags for suppression.

Diagnostic Codes and Actionable Feedback

The failure_reason is where you find the technical “why.” Codes like domain_dns_missing or smtp_timeout (e.g., 301) are standardized enough to map across systems. You can correlate these with known issues—like a mail server timing out after 30 seconds, which is common during greylisting or rate-limiting by recipients.

detailed_code is internal, used only during API debugging. It might be mx_lookup_failed or spf_rejected, helping identify protocol-level breakdowns. The timestamp is always in ISO 8601 format, so it’s easy to parse across systems. Finally, suggestions is optional but valuable: an array like ["verify domain DNS", "check SMTP server availability"] guides your team to fix issues fast.

This schema is how you move beyond “this email bounced” to “here’s why, and how to fix it.” It’s the backbone of real-time verification systems. For a full implementation, see our real-time verification API.

How to Map Error Codes to Real Causes: A Practical Guide

You don’t need guesswork when your real-time verification API returns error codes. Each code maps directly to a known technical or behavioral cause—like an invalid format, a missing DNS record, or a disposable domain. By interpreting these codes correctly, you can automate cleanup rules, reduce bounce rates, and improve sender reputation. We’ll walk through the most common ones and how to act on them.

Common Error Codes and Their Meaning

• Code 101: Invalid local part — The username portion (before @) violates RFC 5322. Examples: [email protected] is valid; user [email protected] or [email protected]! are not. Let’s be clear: spaces, unescaped special characters, and improper quoting break parsing. You can fix this by enforcing regex patterns aligned with the standard.
• Code 203: Domain not found — The domain lacks A or MX DNS records. This means the email address is either typoed or the domain no longer exists. Validate domains before sending using RFC 5321 requirements for MX record presence.
• Code 302: SMTP timeout — The mail server didn’t respond within the expected window, typically due to configuration issues, firewall blocks, or server overload. Even if the domain exists, a timeout means you can’t confirm inbox accessibility.
• Code 405: Catch-all detected — The server accepts all emails for the domain. You can’t verify individual addresses. Treat these as high-risk; they’ll either bounce or land in spam. Use this signal to flag or exclude such domains.
• Code 501: Role-based address — Matches patterns like admin@, support@, or info@. These are often never checked by humans, so they result in high bounce rates. Avoid sending transactional or time-sensitive content to these.
• Code 600: Disposable domain detected — Services like Mailinator, Guerrilla Mail, or TempMail return short-lived inboxes. These are non-reliable for onboarding or marketing. Block these early to avoid waste and keep your sender reputation healthy.

Turning Codes into Actionable Rules

Use these codes in your workflow. Filter out 101 and 203 before sending—no point trying to reach a non-existent format or domain. Flag 405 and 600 for exclusion. Apply automated suppression for 501 addresses when sending to users who need reply tracking.

For the best results, run real-time verification across your list. Use our real-time API to catch these issues at scale. If you’re managing large lists, start with bulk verification to clean your database before campaigns begin.

Why Structured JSON Matters for API Integrations

You need a consistent JSON schema for email validation failures to reliably parse errors across systems. Without it, each API return is a guessing game—your app can't auto-respond to invalid, disposable, or risky addresses. A standard structure lets your workflows treat failure data the same whether you're using Klaviyo, Mailchimp, or your own backend. That’s how you avoid custom logic per vendor and keep list quality high with real-time cleanup.

The Problem: Messy, Inconsistent Data Breaks Automation

If every email verification service sends back errors in a different format—some use error_code, others reason or status_message—your app can’t automate handling them. A failed validation might mean "invalid format," "catch-all," or "blocked by spam filter." Without a shared schema, your system can’t tell which requires action and which is a false alarm. You’re left writing ad-hoc parsers for each integration, which is fragile and hard to maintain.

Consistency Enables Reliable, Scalable Workflows

When failure details follow a standard JSON schema—like the one used in the IETF’s YANG Data Modelling Language for JSON—your backend can process every response the same way. Let’s say your system flags reason: "disposable" or status: "invalid". With a consistent structure, you can build a rule once: “Remove any address where result is invalid or disposable.” That rule runs cleanly across all integrations, including those with Mailchimp or Klaviyo via our real-time integrations.

That same structure supports automated list cleaning too—no manual steps. A failure with type: "risky" might be a high-fraud domain. Your system can log it, flag it for review, or drop it immediately. You’re not just verifying emails; you’re hardening your sender reputation. And since our verification API returns structured JSON with clear, consistent error codes—including invalid_syntax, catch_all, disposable_domain, and risky—you can build reliable logic without guesswork.

Eventually, you’ll stop relying on raw strings or inconsistent fields. You’ll have a real-time, machine-readable way to act on failure data. That’s what enables high deliverability at scale: one schema, one rule, millions of clean emails.

How to Use the JSON Schema in Your Application Logic

You can use the failure_reason and detailed_code fields in the JSON schema to trigger automated responses in your app—like routing invalid emails to cleanup workflows or logging timeouts to monitor server health. The verdict field tells you the root cause, and combining it with structured error codes lets you act fast and prevent repeated failures.

1. Parse the failure_reason and detailed_code in real-time responses. These fields describe the exact failure point, whether it's a syntax error, DNS timeout, or SMTP handshake issue. Use them to decide how to handle each result—fail silently, retry, or flag for review.
2. Map detailed_code values to internal workflows. For example, if you see smtp_timeout, treat it as a network or sender reputation issue. If invalid_syntax appears repeatedly, validate your input pipeline. This keeps your system responsive to real delivery problems.
3. If verdict: disposable, remove the address and log the domain. Disposable emails are temporary; they don’t engage and harm sender reputation. Use a centralized blocklist to prevent future uploads. This is especially important for marketing campaigns. Industry data shows that disposable domains correlate with high bounce and spam rates.
4. Flag domains with verdict: catch-all for suppression. These domains accept all incoming emails, which means you're not validating real users. Sending to them harms deliverability. Mark them in your campaign filters to avoid waste. This is a common practice in B2B list hygiene.
5. Monitor repeated smtp_timeout errors. If you see these consistently across multiple domains, investigate your outbound IP reputation. High volumes or poor history can trigger timeouts. Use tools like MxToolbox to check your IP's presence on blocklists.

Routing Errors to the Right Team

Use the schema to build an alerting system. For instance, a spike in invalid_syntax might signal a form field defect. Frequent mailbox_full codes mean user inbox limits are exceeded—common in older addresses. Forward these to the right team based on the code, not just the verdict.

Testing and Validating Your Logic

Run test batches with known bad and good emails to ensure your application handles each verdict and error code correctly. A real-time verification API like EmailListChecker’s API can help you simulate edge cases and validate your logic before deployment.

How Emaillistchecker.io Implements This Schema Across APIs

Our real-time verification API returns consistent JSON structure under result and failures keys, ensuring you get predictable, machine-readable failure details—no surprises, no format drift. This standardization lets you automate fixes, track patterns, and integrate seamlessly into your toolchain. Whether you're building a signup flow or auditing a campaign list, the schema is designed for reliability and clarity. JSON remains the industry standard for structured data exchange, and we follow it strictly.

Consistent Response Shape for Automation

Every request—whether via our real-time API or batch processing—returns the same core structure. The result key holds individual email verdicts, while failures contains detailed reason codes, like invalid_format, disposable_domain, or mailbox_not_found. This consistency means your code doesn’t need to handle dozens of edge cases—just parse a few known fields. It’s especially valuable in high-volume systems where failure patterns inform routing or error handling.

Bulk verification results include a summary object with counts by verdict type: valid, invalid, catch-all, risky, disposable, and more. You can see at a glance how many addresses are likely to bounce, or whether a list has a large batch of temporary emails. This summary helps you assess list quality before sending—no need to scan through thousands of individual entries.

AI Assistant Uses Failure Context to Improve Lists

Our in-app AI assistant reads the failures details and surfaces actionable insights. For example, if several emails fail due to a common typo pattern, it might say 'suggest fixing “@gamil.com” → “@gmail.com” in 17 entries.' It can flag role accounts like admin@ or support@ when they’re used in transactional contexts. This isn't guesswork; it’s pattern recognition based on the actual failure codes we return.

All validation failures are logged with full context and accessible via our API for debugging or auditing. This includes timestamps, input value, verification verdict, and exact failure reason. You can reconstruct any validation attempt, trace delivery issues back to their root cause, or build compliance records. The full data history is preserved indefinitely—no credit expiry, no lost logs.

Consistent, structured feedback is as important as the check itself. Without it, you’re guessing why your list failed.

Avoiding Common Misinterpretations of Failure Codes

Don’t assume a "catch-all" means the email works — it just means the server accepts mail without checking for a valid recipient. A "risky" verdict isn’t a bounce, but signals low deliverability. "Invalid" includes syntax errors, not just non-existent addresses. Always cross-check the verdict and failure_reason together — one alone can mislead. Think of them as twin signals in a real-time verification system.

You're not seeing the full picture if you only read the verdict

• Don’t treat a catch-all as a pass — it means the server doesn’t verify individual mailboxes, so messages may still be rejected or sent to junk folders. According to RFC 5321, this is not a guarantee of inbox delivery.
• A risky verdict indicates the server may accept mail, but the domain or IP has low reputation or known spam behaviors. It’s not a failure, just a warning — treat it as a deliverability red flag, not a bounce.
• Validating syntax alone doesn't confirm inbox receipt. An invalid verdict includes malformed formats (like missing @ or domain), domain tld issues, or email addresses that fail DNS checks — this is a delivery barrier, not just a typo.
• Never rely on verdict alone. Combine it with failure_reason to avoid misclassification. For example, "invalid" with reason "syntax" is different from "invalid" with reason "domain not found".
• Use real-time verification tools like our API to get both values in one response — this eliminates guesswork when cleaning lists at scale.

What the data actually means (and what it doesn’t)

• When verdict says valid but failure_reason says greylisted, the email is likely deliverable — just delayed. Greylisting is a common anti-spam measure, but not a hard fail.
• Never assume catch-all leads to inbox delivery. Some services use it for security — messages may still be dropped in spam folders or quarantined.
• If you see disposable or role in failure_reason, those are not hard failures — but they impact deliverability and engagement. Role accounts (like admin@) are often ignored.
• Don’t treat unknown as a synonym for "invalid" — it means the server didn't respond. Use tools like bulk verification to detect patterns and validate results at scale.
• Always verify your logic by testing with sample emails across different domains — a single failure reason may behave differently across MX servers.

The Role of Accuracy in Real-Time Validation: 98.9% Matters

At 98.9% accuracy, our real-time verification API ensures that nearly every email verdict is correct—meaning only 1.1% of checks are misclassified, even at scale. That level of precision makes the JSON schema for validation failures trustworthy for automation, compliance, and decision logic. You can rely on each field in the response without manual review.

Why Accuracy Directly Impacts Schema Reliability

When your system consumes JSON output from a verification API, you need to know the data reflects reality—not guesswork. A misclassified email as "valid" when it’s actually invalid can trigger bounces, hurt sender reputation, and reduce inbox placement. At 98.9%, the error rate is low enough to trust the schema outputs as input for downstream processes—like list hygiene or onboarding workflows.

For example, if the schema returns "reason": "syntax" or "reason": "disposable", you can act immediately. But if those classifications are wrong even 5% of the time, your automation breaks down. That’s why accuracy isn’t just a number—it’s the foundation of trust in any real-time verification pipeline.

Long-Term Trust Without Budget Friction

Accuracy matters most when you're building long-term verification systems. You don’t want to re-budget every month because you burned through credits. Our API gives you 100 free verifications to start, and the credits you buy never expire—no time limits, no pressure to spend fast. That means you can set up a pipeline today, scale it over months, and still have unused credits later.

Whether you're integrating with SendGrid, HubSpot, or Klaviyo via our integrations, or running bulk checks through bulk verification, consistency in output means fewer surprises. A 98.9% accuracy rate translates to fewer false positives and fewer bounces from invalid addresses you didn’t catch.

Real-world systems face challenges like catch-all domains, greylisting, or role-based emails. Our detection process accounts for these through layered checks—DNS, SMTP, and syntax validation—so the JSON schema returns accurate, actionable feedback. This is how you move from reactive cleanup to proactive list quality.

For reference, industry-standard deliverability thresholds often cite a 95%+ accuracy benchmark as ideal for maintaining sender reputation. We exceed that, which is why major teams use the API to power automated workflows without constant oversight.

Conclusion: Build Smarter Validation Systems with Standardized JSON

Without a consistent structure, failure details from email validation are difficult to process, interpret, or act on at scale.

A well-defined JSON schema ensures every validation response carries the same predictable format, enabling automation, faster debugging, and sustained list hygiene across systems.

Emaillistchecker.io delivers this structure in every real-time verification, with 98.9% accuracy across all responses.

Use standardized JSON to improve deliverability, reduce bounce rates, and protect sender reputation over time.

Sources

• Real-time verification at signup caught more than 10 million typo email addresses in one year, preventing those bounces before they ever hit a list. — ZeroBounce Email List Decay Report (2025)

Keep reading

• Email Verification API & SDKs: the complete developer guide (complete guide)
• Email Verification Systems That Handle High Volume with Minimal Latency
• Email Verification API That Returns Compressed NDJSON for Batch Processing
• Are Disabled addy.io Aliases Still Accessible via API Endpoints?
• Email Verification API That Identifies Forwarding Loops via Received Headers

Ready to put this into practice? Emaillistchecker.io verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What does a 'catch-all' verdict mean in email verification?

It means the domain accepts all emails, even invalid ones, making it impossible to confirm individual mailboxes. Such addresses should be avoided in campaigns.

Can I use the JSON schema for bulk list verification?

Yes — the same schema format applies to bulk results, with each entry containing structured failure details.

How do I handle SMTP timeout errors in real-time verification?

Timeouts (detailed code 302) usually indicate server issues, poor connection, or IP reputation problems. Retry with backoff or check your outbound IP.

What are disposable email domains, and how does the JSON schema identify them?

Disposable domains are short-lived email services. The schema tags them with 'verdict: disposable' and 'detailed_code: disposable_domain'.

Why does my API return 'invalid' for a valid-looking email?

It likely fails syntax checks — like missing @ or invalid characters. Check the 'reason' field for specific issues like 'syntax_error'.

How does Emaillistchecker.io’s accuracy impact the JSON schema reliability?

With 98.9% accuracy, the schema fields reflect real-world conditions, making error decisions trustworthy for automation.

Can I customize the JSON schema output from Emaillistchecker.io?

No — the schema is fixed and standardized. This ensures compatibility with integrations and third-party tools.

How do role-based addresses affect deliverability?

Addresses like 'support@' or 'info@' often have high bounce rates. The JSON schema flags them as 'risky' to warn against use in mass campaigns.

What happens if I get many 'domain_dns_missing' errors?

It likely means the domain lacks DNS records (A or MX). Verify DNS configuration or remove the domain from your list.

Do verified emails with 'risky' verdicts ever reach inboxes?

They may, but deliverability is low. These should be tested via inbox placement tools before full-scale send.

How do I test my JSON schema integration?

Use our 100 free verifications to test responses. Compare results in real-time and validate error parsing across multiple scenarios.

Is the JSON schema compatible with Mailchimp or HubSpot?

Yes — the consistent structure allows easy parsing in any system that handles API responses with JSON.