How to Extract Hard Bounce Subtypes from Mailgun JSON Response

Why Hard Bounce Subtypes Matter for List Hygiene

You send a campaign. A few days later, Mailgun reports a hard bounce. You mark the address as invalid and move on. But what if that bounce didn’t mean the email was dead—as a user, you’d be surprised to learn that not all hard bounces are created equal.

Hard bounces are the most reliable signal that an email is unreachable. But digging deeper—into the subtype within the Mailgun JSON response—reveals whether the issue is a permanent failure (like a defunct address or closed domain) or something that might resolve itself (like a policy block or transient server error). Ignoring these distinctions leaves your list polluted, damages sender reputation, and increases the risk of being flagged by blacklists.

Knowing how to extract hard bounce subtypes from Mailgun’s JSON response isn’t just technical trivia—it’s a critical step in maintaining list hygiene, preventing wasted sends, and preserving long-term deliverability.

Key takeaways

• Hard bounce subtypes from Mailgun JSON reveal whether an email is permanently invalid or temporarily blocked.
• Ignoring subtypes leads to persistent sends to non-deliverable addresses, harming sender reputation.
• Correctly parsing subtypes allows for targeted cleaning—removing only truly dead addresses while preserving recoverable ones.

How Mailgun Reports Bounce Subtypes in Its JSON Response

You can extract hard bounce subtypes from a Mailgun JSON response by inspecting the type and description fields in the event payload. When type is hard, the description often contains an SMTP error code and a human-readable reason, like 550 5.1.1 <[email protected]>: Recipient address rejected: User unknown, which is a concrete, actionable hard bounce subtype. This allows precise filtering and remediation.

Understanding Mailgun's Event Payload Structure

When Mailgun delivers a bounce event, it sends a JSON payload via webhook or API. The type field tells you whether the bounce is hard (permanent) or soft (temporary). A hard bounce indicates the address is invalid, often due to a non-existent recipient or a rejected domain.

The description field contains the detailed reason — usually an SMTP reply code (like 550, 551, or 552) followed by a descriptive message. For instance, 550 5.1.1 means the recipient address does not exist, and 554 5.7.1 means the message was rejected due to policy or spam filtering. These codes are defined in RFC 5321 and RFC 5322, which outline SMTP behavior and error responses.

How to Use Bounce Subtypes for List Hygiene

Leveraging these subtypes lets you automate removal of invalid addresses. For example, if you see 550 5.1.1, 550 5.7.1, or 550 5.2.1 in the description, you can safely remove those emails from your list to prevent future bounces and protect sender reputation. In contrast, 550 5.2.2 (mailbox full) or 450 4.2.1 (temporarily unavailable) are soft bounces — they may resolve on retry but should still be monitored.

With this level of detail, you can build filters in your application to handle bounces at the subtype level, rather than treating all hard bounces as interchangeable. For teams using Mailgun, this structured insight is key to maintaining high deliverability and reducing waste.

If you're processing large volumes of Mailgun events, a real-time email verification API can help preemptively filter invalid addresses before they enter your system. See how Email List Validation’s real-time verification API integrates with your workflows and reduces bounce rates before sends happen.

The Common Hard Bounce Subtypes You’ll See in Mailgun’s JSON

When Mailgun returns a hard bounce, its JSON response includes a code and human-readable subtype. You’ll see five common ones: 550 5.1.1 (user unknown), 550 5.2.1 (mailbox disabled), 550 5.7.1 (sender blocked), 554 5.7.1 (spam detected), and 450 4.7.1 (temporary failure). Each tells you whether the issue is permanent or temporary, and what action to take — like removing invalid addresses or fixing sender reputation. Understanding these subtypes is key to cleaning lists and improving deliverability.

Mapping Mailgun’s Bounce Codes to Real-World Issues

Not all bounces mean the same thing. Let’s break down what each code in Mailgun’s JSON actually means — and how to act on it.

Why Subtype Matters for List Health

Knowing the subtype separates actionable issues from noise. A 550 5.1.1 means you can remove an address with confidence. A 450 4.7.1 means you should delay retry attempts, not delete. Ignoring the difference risks damaging sender reputation by retrying permanently failed addresses.

Use a tool like email list validation to catch these issues before sending — it identifies invalid, risky, or non-existent addresses using real-time SMTP checks and MX validation. This reduces bounce rates and protects deliverability over time.

How to Parse Hard Bounce Subtypes from Mailgun's Event JSON Using Code

You can extract hard bounce subtypes from Mailgun’s JSON response by first filtering webhook or API events where type is bounce and subtype is hard. Then, parse the description field using a regex like /\d{3} \d\.\d\.\d/ to isolate the SMTP error code (e.g., 550 5.1.1). Map this code to known subtypes—like 550 5.1.1 for invalid mailbox—using a lookup table for automated cleanup or suppression.

Step-by-step: Extracting and Mapping Bounce Codes

1. Receive the Mailgun event payload via webhook or fetch it from the Mailgun Events API endpoint. The payload includes metadata like type, subtype, and description.
2. Filter for events where type is bounce and subtype is hard. Hard bounces indicate permanent delivery failure and should be removed from your list immediately.
3. Extract the description field and apply the regex pattern /\d{3} \d\.\d\.\d/ to isolate the SMTP error code. This pattern matches structured error codes used in protocols like RFC 5321 and RFC 5322.
4. Map the extracted code (e.g., 550 5.1.1) to a known subtype. For example, 550 5.1.1 typically means "mailbox does not exist," while 554 5.7.1 indicates a rejected message due to policy.
5. Automate list hygiene by tagging or suppressing email addresses with specific codes. This improves sender reputation and reduces future bounces.

Why This Matters for Deliverability

Ignoring hard bounce subtypes means you’re treating all bounces as equal—when in fact, error codes reveal the root cause. For example, a 550 5.1.1 requires suppression, while a 554 5.7.1 may need sender policy review. Without this distinction, you risk damaging your sender reputation.

You can pre-empt hard bounces by validating your list before sending. Bulk email list cleaning removes invalid, catch-all, and disposable addresses before they ever hit Mailgun, reducing bounce rates and improving inbox placement. For real-time verification, use the real-time verification API to scrub addresses on signup.

Why Manual Extraction Is Not Scalable for Large List Hygiene Workflows

You can’t maintain inbox deliverability at scale by parsing Mailgun’s JSON bounce responses by hand. With thousands of bounces, each requiring inspection for subtypes like 5.7.1 (sender blocked) or 5.1.1 (mailbox unknown), manual review is slow, inconsistent, and prone to missing critical signals. Even a single overlooked permanent error can degrade sender reputation and hurt deliverability over time.

Volume Turns Review into a Bottleneck

Imagine reviewing 10,000 bounce entries one by one. Each JSON response contains nested fields like error, type, and detail—but only a few lines actually matter for blocking or cleaning. Human reviewers can’t reliably scan that volume without fatigue, making it easy to miss patterns like recurring 5.7.1 errors from a specific domain.

And even if you spot one, manually logging it doesn’t prevent future sends. Without automation, you’re re-sending to known bad addresses, wasting resources, risking blacklisting, and degrading your sender reputation. This is especially risky because a single 5.7.1 — often indicating a policy-level block — means the address is never going to receive mail again.

Automation Catches What Humans Miss

Mailgun’s bounces follow SMTP standards, but their meaning varies by provider. For example, a 5.7.1 from Gmail means something different than the same code from Outlook. You need logic to distinguish permanent failures from transient ones, and that’s not feasible at scale with manual inspection.

Real-time systems using standardized validation rules—like checking against known blocklists, verifying domain MX records, and parsing DNS-based feedback loops—can flag these patterns instantly. Tools like bulk email list cleaning can process an entire list in minutes, identifying invalid, risky, or permanently unreachable addresses before a single campaign runs.

As the RFC 6522 details, SMTP error codes are the standard language of email delivery. But interpreting them correctly—especially in bulk—requires automation, not hours of spreadsheet work. Let systems do what they’re built for. You focus on strategy, not triage.

How Email List Validation Helps Automate Hard Bounce Subtype Analysis

You can extract hard bounce subtypes from Mailgun JSON responses by mapping error codes to known delivery failures, but manually doing this at scale is slow and prone to error. Email List Validation automates this by analyzing historical bounce patterns, cross-referencing error codes with industry-standard definitions — like those in RFC 5321 and RFC 6522 — and surfacing structured verdicts before you send. This reduces waste, improves sender reputation, and cuts down on deliverability surprises.

How It Works in Practice

• Use our real-time verification API to flag invalid, catch-all, or risky addresses before they hit your Mailgun queue.
• For bulk lists, run bulk email list cleaning to get structured verdicts: valid, invalid, catch-all, or risky — each with a technical explanation.
• Our engine analyzes past bounce metadata from your Mailgun or SendGrid logs and maps error codes like 550 (user unknown), 551 (user not local), or 553 (invalid mailbox) to their likely root cause.
• We cross-reference known patterns from RFC 5321 and RFC 6522 to distinguish between temporary issues and permanent failures like invalid syntax, blocked domains, or role-based accounts.
• With integrations to SendGrid and Mailgun, you can sync your bounce data with our verification engine so we can train on your historical patterns and refine predictions.

Why This Matters

Hard bounces aren’t just a number — they break sender reputation if left unchecked. Ignoring subtypes like "mailbox not found" vs. "domain doesn’t exist" leads to poor list hygiene and higher inbox placement rates. Our system detects subtle distinctions: a catch-all domain (where any address works) is often a signal of low engagement or spoofing attempts. A role account (like admin@ or info@) may not be the target and is prone to spam filtering.

By using real-time and bulk verification, you stop sending to known dead ends before they ever get logged as bounces. You avoid blacklists, maintain consistent sender reputation, and keep delivery rates stable. This isn’t about guessing — it’s about using data and logic to eliminate noise from your campaign pipeline.

How to Use Email List Validation to Pre-Filter Bounce-Prone Addresses

You can extract hard bounce subtypes from Mailgun’s JSON responses by first cleaning your list before sending. Use Email List Validation to identify invalid, catch-all, and role-based addresses that cause hard bounces—then remove them before hitting Mailgun. This cuts delivery failures from 8% down to under 1% in most campaigns. Let’s walk through how.

Pre-emptive Verification Reduces Bounce Risks

Instead of waiting for Mailgun to return bounce codes, catch problems early. Upload your list to Email List Validation for bulk verification. It checks each address against real-time SMTP, MX, and domain validation—no guesswork.

1. Upload your list to Email List Validation’s bulk verification tool. Support for CSV, Excel, and plain text formats. It processes thousands of emails in minutes, delivering results in under 15 minutes for 10,000 addresses.
2. Review the results. Invalid emails—including those with hard bounce subtypes like “550 5.1.1 User unknown” or “550 5.2.1 Recipient address rejected”—are flagged with clear verdicts. You’ll also see catch-alls, role accounts (e.g. info@, admin@), and disposable domains.
3. Export the cleaned list. Only valid, deliverable addresses remain. You can filter out any high-risk types, including outdated or structurally invalid emails.
4. Re-upload via API or integration. Connect Email List Validation to Mailgun through its API or via integrations in platforms like HubSpot, Klaviyo, or SendGrid. This ensures only verified addresses reach your sending gateway.

According to industry benchmarks, lists with Spamhaus data, 8% of emails bounce on average—mostly due to poor list hygiene. After pre-cleaning, bounce rates drop to below 1%. The difference is measurable in inbox placement and sender reputation.

Why This Works: Real-Time Checks, Not Post-Event Fixes

Mailgun’s JSON bounce responses are informative but reactive. You learn of a failure after it costs you bandwidth, reputation, and deliverability. Email List Validation acts before sends happen—validating at the protocol level via real SMTP handshake, checking MX records, and testing domain behavior.

It’s not just about removing invalid addresses. The tool also identifies risky patterns: role accounts often trigger spam filters, and catch-alls may be accepted but never opened. By filtering these out, you reduce engagement penalties and protect domain reputation.

For developers, Email List Validation offers a real-time API that fits into your workflow. No need to parse Mailgun JSON responses manually—just validate at point of capture or import.

Best Practices for Managing Hard Bounce Data in Your Email Infrastructure

Extracting hard bounce subtypes from Mailgun's JSON response lets you act faster and smarter: classify why an email failed (invalid, blocked, unknown), auto-suppress repeat offenders, flag risky addresses for review, and track list health over time. This reduces bounce rates, protects sender reputation, and keeps your deliverability strong.

• Store each hard bounce subtype (e.g., "550 5.1.1") in a structured database with clear classification fields like reason, type, and severity. This lets you analyze trends across campaigns and domains.
• Set up a rule to suppress any email address that triggers the same hard bounce code (e.g., “550 5.1.1”) three times in a row. This prevents repeated delivery attempts that can hurt your sender reputation with providers like Gmail and Outlook.
• Use the 'risky' verdict — common for role accounts like admin@ or support@, or disposable domains — to trigger internal review workflows. These addresses rarely convert and often cause delivery issues.
• Monitor your list health weekly. Compare your current bounce rate against a baseline from a 10,000+ email list verified with a trusted service. This baseline helps you distinguish normal noise from real degradation.
• Integrate your bounce processing pipeline with a real-time verification API to catch invalid addresses before they ever hit the send queue. Verify emails in real time with 98.9% accuracy.

Why This Works

Mailgun returns detailed bounce codes, but only if you parse them. Most teams ignore subtypes and treat all hard bounces the same. That’s expensive. According to the SMTP RFC 6521, error codes like 550 (permanent failure) or 551 (user unknown) should be treated differently than transient issues. Ignoring the difference leads to bad decisions.

Automating suppression based on repeated codes cuts down on unnecessary traffic. A study from Return Path showed that consistent, high-volume hard bounces lead to IP reputation drops within 2–4 weeks. Let’s not wait that long.

Role accounts or disposable emails—often flagged as 'risky'—are not just noise. They’re signal. They indicate weak lead quality and can skew analytics. By tagging and reviewing them, you keep your list clean and your engagement metrics honest.

Pro Tip: Start with a Verified Baseline

Before you can monitor health, you need a benchmark. Run your current list through a bulk verification tool. Clean your list now to see what your real bounce rate looks like with valid addresses only.

Why You Shouldn’t Rely on Mailgun’s Bounce Logs Alone for List Hygiene

You can’t fix poor deliverability by reacting to bounces after they happen. Mailgun’s logs only show what failed after a message was sent—meaning you’ve already sent to invalid addresses, hurt your sender reputation, and burned reputation points before you even knew the email was bad. Relying solely on post-send feedback leaves you behind the curve and unable to catch invalid addresses before they ever get sent.

Mailgun’s Bounce Logs Are Reactive, Not Preventive

Mailgun’s bounce logs are a record of what failed, not a warning system for what might fail. They surface hard bounces only after your message hits the wall—often days or weeks after sending. By then, your IP and domain have already taken a hit from repeated failures, even if you’re cleaning the list later.

And since hard bounces only appear after delivery attempts, you’re missing out on catching invalid addresses that never get delivered at all. Some domains outright reject unverified emails before they even reach the server. If you send to a catch-all or a role-based address with a typo, Mailgun may never tell you—because it won’t generate a bounce at all.

You’re Sending to Dead Addresses Before You Even Know

Without pre-verification, every email you send carries a risk. The moment you send to an outdated, misspelled, or non-existent address, you’re adding to your sender reputation score negative weight—even if you correct it later. According to the [DMARC Report](https://dmarc.org/), sender reputation is influenced by consistent delivery success rates, and failed attempts—even one—can trigger scrutiny.

Let’s say you send to 10,000 emails with 50 invalid addresses. Even if 45 are hard bounces, the 5 you never see a bounce from still harm deliverability. Their addresses are dead, but your server thought they were valid. That’s 5 wasted sends, 5 reputation points lost, and no way to know they were wrong until too late.

That’s why you need to verify emails before sending. Real-time verification tools like email verification APIs or bulk cleaning services can identify invalid addresses with over 98% accuracy—before you send. You’re not waiting for bounces; you’re preventing them.

How the Email List Validation API Complements Mailgun’s Bounce Tracking

You can extract hard bounce subtypes from Mailgun’s JSON response by parsing the event data—specifically, the delivery.status and bounce.reason fields. But that’s only half the story. The real power comes from validating emails before sending, using an API that returns structured reasons like “user unknown” or “domain not found,” so you never send to addresses that will bounce in the first place. This combination lets you catch errors early and react faster to actual delivery issues.

Why Pre-Send Validation Matters

• Mailgun tracks bounces after they happen. Our API checks validity in real time, so you know which emails are invalid before they’re sent.
• It returns a clear verdict and reason—like invalid, catch-all, or role account—so you can act on data, not just logs.
• Filter out addresses with known issues like non-existent domains or closed inboxes before your campaign runs, reducing waste and protecting sender reputation.
• Unlike Mailgun’s generic “hard bounce” flag, our API distinguishes between structural flaws (e.g., typo in domain) and temporary blocks (e.g., greylisting), enabling smarter filtering.
• Use our real-time verification API to integrate with your sending workflow, ensuring clean data at the moment of transmission.

Combining Pre-Send and Post-Send Intelligence

• Mailgun’s event logs show what went wrong after a send. Our API shows what you could have avoided before it left your server.
• When paired, you get a full timeline: pre-check (validity score), post-check (delivery outcome), and context (bounce subtype).
• For example, if a user’s email returns user unknown in our API, and Mailgun later logs a “hard bounce,” you’ve confirmed the address was never valid—which means it was never your fault.
• Some providers use catch-all policies or role-based addresses that appear valid but never deliver. Our system flags these as risky or catch-all upfront, reducing false positives in your bounce tracking.
• Studies from Spamhaus and RFC 5321 show that invalid domains and malformed addresses are primary causes of early bounce events—this is why proactive validation improves deliverability.

Final Step: Cleaning Your List to Prevent Future Bounce Issues

Once you’ve identified hard bounce subtypes in your Mailgun JSON responses, the next step is proactive list hygiene. Run your entire email list through Email List Validation’s bulk verification system to catch invalid and risky addresses before they cause issues.

Remove all addresses marked as 'invalid' or 'risky.' Keep only those verified as 'valid.' For 'catch-all' addresses, flag them for manual review—these may accept messages but offer no delivery confirmation.

This process eliminates hard bounces, maintains sender reputation, and improves deliverability by ensuring only high-quality addresses remain on your list.

Keep reading

• Bounce management: hard bounces, soft bounces and bounce rate (complete guide)
• How to Avoid 553 5.1.8 Bounce Codes with an Email Deliverability Platform
• Pre-Send Email Analysis Tool to Prevent 554 5.7.1 Spam Filtering
• Fixing 550 5.1.0 Invalid Address Format: What It Means
• What Does 552 5.2.2 Mean in Amazon SES Delivery Logs?

Ready to put this into practice? Email List Validation verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What is a hard bounce subtype in Mailgun?

A hard bounce subtype is a detailed error code in Mailgun’s response that explains why delivery failed permanently, such as '550 5.1.1: User unknown'.

Can I extract hard bounce subtypes without code?

Not reliably at scale. Manual parsing is error-prone. Automating extraction with code or using a verification service like Email List Validation is recommended.

Why do I need to know the difference between hard bounce types?

Different subtypes signal different underlying issues—some indicate invalid addresses, others show sender policy blocks. Acting on the right subtype improves list hygiene and deliverability.

How accurate is Email List Validation’s verification?

It achieves 98.9% accuracy by combining real-time SMTP checks, domain analysis, and pattern recognition across verified data.

Does Email List Validation work with Mailgun?

Yes. It integrates directly with Mailgun and other platforms like SendGrid, Klaviyo, and HubSpot to validate lists before sending.

Do I need to verify every email address in my list?

Yes. Unverified lists often contain invalid, role, or disposable emails that increase hard bounce rates and harm sender reputation.

What happens if I don’t clean my list after hard bounces?

Your sender reputation degrades, delivery rates drop, and you risk being blocked by major ISPs and blacklist services.

Can I use free credits to verify a large list?

Yes. You receive 100 free verifications to start. Purchased credits never expire, so you can plan your verification strategy over time.

How does Email List Validation detect catch-all addresses?

It uses SMTP probing and response analysis to identify domains that accept all incoming mail, flagging such addresses as high-risk.

Is real-time API verification faster than batch processing?

Yes. Real-time verification is ideal for dynamic user signups, while batch verification is best for large list cleaning before campaigns.

How does Email List Validation handle disposable email domains?

It identifies and flags known disposable domains using an up-to-date database of short-lived email providers.

What if I’m unsure about the meaning of a Mailgun bounce code?

You can cross-reference the code with known SMTP error standards or use Email List Validation’s AI assistant to decode it.