Parse Mailgun Delivery Response for Permanent Bounce Subtypes

Why ignoring Mailgun’s permanent bounce subtypes hurts your deliverability

You send an email campaign. Mailgun reports a bounce. You flag it, move on, and assume the address is gone. But what if that bounce was a specific "user unknown" or "mailbox full" — and you didn’t know the difference?

Mailgun’s delivery response includes precise subtype codes for each bounce. Ignoring them means treating all failures as the same. That’s like throwing a whole batch of expired tickets into your system because one was rejected — you miss the ones that aren’t dead yet.

Parsing Mailgun’s permanent bounce subtypes isn’t optional. It’s how you distinguish between addresses that are permanently invalid and those that might still work. Without it, your list stays cluttered, your sender reputation suffers, and your inbox placement drops — silently.

Key takeaways

• Mailgun’s delivery responses contain subtype codes that identify the exact reason for a permanent bounce.
• Failing to parse subtypes leads to poor list hygiene, as permanently invalid addresses remain in your list.
• Correctly identifying bounce subtypes allows you to maintain sender reputation by avoiding repeated sends to addresses that will never accept mail.

What are permanent bounce subtypes in Mailgun’s delivery response?

Permanent bounce subtypes in Mailgun’s delivery response are specific failure codes in the reason field of the bounce webhook payload that indicate why an email was permanently rejected—such as an invalid address, a full mailbox, or being blocked. You’ll see these in responses from the recipient’s mail server, and each subtype helps you diagnose and clean your list more precisely. Common ones include userunknown, no-mailbox, mailboxfull, blocked, and rejected, which signal distinct delivery issues.

Understanding the most common subtypes

When Mailgun returns a permanent bounce with the userunknown reason, it means the mailbox doesn’t exist on the recipient server—this often happens with typos or defunct accounts. If you see no-mailbox, the address was never set up or was deleted, which signals a clear data quality issue. A mailboxfull bounce is temporary in intent but counts as permanent in the webhook because the user must resolve it manually. The blocked subtype usually means the sender’s IP or domain is on a blocklist, which affects sender reputation and deliverability. Lastly, rejected indicates the server explicitly refused delivery, often due to policy, DNS-based filtering, or content triggers.

These subtypes are standard across email delivery systems and follow industry practices described in RFC 6522, which defines bounce response codes. You can use them to categorize bounces and automate list cleanup—like removing invalid addresses before a new send. For deeper analysis, tools that map these codes to real-world outcomes can help you prioritize list hygiene tasks. A single blocked bounce might point to infrastructure issues, while many userunknown replies suggest outdated data.

When integrated with an email validation service, these subtypes can be pre-emptively filtered. For example, bulk email list cleaning can catch invalid or risky addresses before they even hit Mailgun, reducing bounce rates and protecting sender reputation. If you’re parsing bounces and need to validate or enrich the list post-delivery, our real-time verification API can help confirm addresses at scale.

How to parse Mailgun delivery responses for permanent bounce subtypes

You can identify permanent bounce subtypes from Mailgun’s delivery response by extracting the reason field from the bounce webhook, filtering for type values like bounce, unsub, or complaint, and checking if reason contains specific codes such as userunknown or no-mailbox. When type is bounce and reason includes permanent, treat it as a critical delivery failure. Store these results in a structured format to remove invalid addresses from your list.

Step-by-step: Extract and classify critical bounces

1. Receive the webhook event from Mailgun and extract the type and reason fields. The type tells you the nature of the event (e.g., bounce), while reason contains the underlying cause, such as userunknown.
2. Filter events where type is bounce, unsub, or complaint. These indicate actions that permanently block delivery or signal strong user disengagement.
3. Inspect the reason value. Look for known permanent failure codes like userunknown, no-mailbox, unknown-user, or blocked. These are definitive signs the address is no longer valid.
4. Apply a conditional check: if type is bounce and reason contains permanent, classify the bounce as critical. This helps distinguish it from temporary issues like rate limiting or transient server errors.
5. Store each flagged address in a structured format, such as a CSV, database, or CRM field, marked as inactive. Use this data to clean your list and prevent future sends to invalid addresses. This reduces bounce rates and protects sender reputation.

Why this matters for deliverability

Permanent bounces hurt your sender reputation. According to data from Return Path, consistently sending to invalid addresses can lead to inbox placement drops or blacklisting. Mailgun’s response codes are based on standards like RFC 5321 and RFC 5322, which define how mail servers report failures. Proper parsing ensures you’re not ignoring systemic delivery issues.

Let’s say you see reason: "User unknown" in a bounce event. That’s not a temporary glitch — it’s a fixed problem. If you don’t remove it, you’ll keep sending to a non-existent mailbox, which erodes trust with receiving servers over time.

To complement this process, consider using an email verification tool to catch similar issues before sending. Bulk email list cleaning reduces the chance of permanent bounces by identifying invalid addresses early, improving your overall deliverability and sender score.

Real-world examples of how Mailgun subtypes differ in impact

When Mailgun returns a delivery response with a permanent bounce subtype, such as userunknown or no-mailbox, that address is almost certainly invalid and should be removed from your list. A mailboxfull may be temporary, but repeated failures indicate an inactive or problematic address. A blocked status means the sender's reputation or domain is on a blocklist—worth investigating, but not always a bad address. Understanding these distinctions prevents unnecessary retries and protects sender reputation.

Permanent failures: userunknown and no-mailbox

If Mailgun reports userunknown, the recipient’s email address doesn’t exist on the target domain. This is a definitive permanent bounce—no retry is useful. Similarly, no-mailbox means the mailbox is technically unreachable due to missing configuration or DNS errors. Both indicate invalid or outdated addresses. In either case, treating these as permanent is the right move; persisting wastes resources.

According to RFC 5321, these responses signal that the recipient’s system has confirmed the address does not exist. While rare, some automated systems may return no-mailbox on misconfigured mail servers. You can verify such cases with a real-time validation tool that checks syntax, domain existence, and mailbox reachability before sending [RFC 5321, Section 4.2].

Temporary vs. persistent flags: mailboxfull and blocked

Mailgun marks a mailboxfull failure when the recipient's inbox is full. This is temporary—up to 30 days in some cases—but if returned repeatedly for the same address, it's a red flag. The address may be inactive or no longer monitored, meaning even when space is freed, deliverability won’t improve. A blocked status doesn’t confirm the address is invalid, but it does mean your domain or IP is on a blocklist. The address might still be valid, but sending to it carries a high risk of being rejected.

Blocklist issues are common in bulk campaigns. If you see blocked frequently, check your sending domain’s reputation using tools like MXToolbox or Spamhaus. You can prevent this by cleaning your list before sending—use a verified endpoint that checks for syntax, domain validity, and active mailbox status before you send.

How Email List Validation helps parse and act on Mailgun bounce data

You can avoid sifting through Mailgun’s raw delivery responses by using Email List Validation to catch permanent bounce subtypes—like invalid domains, non-existent addresses, or blocked senders—before you send. Our real-time verification API checks against current DNS, MX, and SMTP records, flagging permanent failures instantly. This means you identify invalid emails faster than waiting for Mailgun to return a bounce, reducing wasted sends and protecting sender reputation.

Instant detection of permanent failures

Mailgun’s bounce responses often arrive hours or days after delivery attempts. By contrast, our verification API runs checks in real time, using up-to-date DNS and SMTP diagnostics to assess email validity before any message is dispatched. This prevents your campaigns from triggering permanent bounces like "550 User unknown" or "551 Undeliverable" at scale.

We return structured verdicts—invalid, catch-all, risky—that align with Mailgun’s own bounce subtype logic. For example, an "invalid" status maps directly to subtypes like "550 5.1.1" (mailbox not found), while a "catch-all" indicates the domain accepts all emails, making delivery pointless. You don’t need to reverse-engineer codes—our system mirrors Mailgun’s behavior, so your automation and alerting workflows are immediately actionable.

Pre-send cleaning reduces bounce risk

Our bulk verification tool processes entire email lists before sending, eliminating permanent failures like invalid domains or blocked IPs ahead of time. This cuts bounce rates significantly, especially for lists with outdated or poorly maintained addresses. According to industry benchmarks, even a 5% reduction in hard bounces can improve inbox placement over time, as ISPs favor senders with consistent deliverability.

Instead of relying on post-delivery feedback to clean your list, you clean it upfront. This improves sender reputation, avoids blacklisting, and keeps your deliverability scores high. You’re not waiting for Mailgun to tell you something failed—you’re preventing the failure from happening in the first place.

For teams using Mailgun, integrating our API or using the bulk verification tool offers a faster, more reliable way to handle bounce data. By acting on validity early, you align with industry best practices—such as those outlined in RFC 5322, which governs email address syntax and delivery semantics.

Common pitfalls when filtering Mailgun bounces without parsing subtypes

You’re likely misclassifying bounces if you’re treating all Mailgun delivery failures the same. Ignoring subtype details leads to removing valid users, missing recoverable temporary errors, and accidentally targeting spam traps. The real fix: parse the full bounce response to separate permanent failures like no-mailbox from temporary ones like temperror, and distinguish between userunknown and no-mailbox to avoid false positives. This is how leading deliverability teams keep their lists clean without over-cleaning.

Missing the difference between permanent and recoverable failures

• Mailgun returns a permanent bounce tag for hard fails, but the subtype reveals whether it’s a user not found, a non-existent domain, or a blocked address. Treating all permanent bounces the same means you might drop a temporary user who just had a mail server hiccup.
• Without parsing subtypes, you’ll apply blanket removal rules that harm deliverability. A temporary failure like 4xx or temperror might resolve in 48 hours — but if you auto-remove based on a broad tag, you lose a real user.
• Use RFC 6522 as a reference: SMTP-level bounce codes (like 550, 551, 552) are standardized and tied to specific failure types. Your logic should reflect that precision.

Failing to distinguish between userunknown and no-mailbox

• userunknown typically means the mailbox doesn’t exist — a hard failure. But no-mailbox can indicate a server-level rejection or a policy block, not a missing user. Confusing the two leads to over-cleaning.
• For example, no-mailbox might come from a catch-all system that accepts but doesn’t deliver mail. If you treat it like userunknown and remove it, you’re tossing a potentially valid account.
• Let’s say your system sees thousands of bounces tagged with permanent — now you’re filtering them all. Without subtypes, you might purge 20% of your list that’s actually recoverable or still active. Use Mailgun’s own documentation to see actual examples of subtype behavior.

When you parse the full response, you’re not cleaning lists — you’re refining decisions. Real-time verification tools like email verification APIs can help preempt these issues by catching invalid addresses before you send.

How to integrate Mailgun bounce parsing with your list hygiene workflow

You can parse Mailgun delivery responses for permanent bounce subtypes by setting up a webhook to capture bounce events, extracting the type and reason fields, then using an email verification service to cross-validate addresses marked as permanently failed. This allows you to automatically purge invalid emails within 24 hours, reducing bounces, protecting sender reputation, and ensuring compliance. Mailgun’s delivery status reports are a reliable source for real-time feedback, and integrating them into your workflow aligns with industry best practices for email list hygiene.

Step-by-step: Parsing and acting on Mailgun bounces

1. Set up a webhook in your Mailgun app to receive bounce events. Mailgun sends HTTP POST payloads to your endpoint whenever an email fails delivery. Ensure your server accepts these payloads and logs them for auditing. This step is foundational — without it, you won’t detect failures.
2. Parse the type and reason fields from the incoming JSON. A type of permanent indicates a delivery failure that won’t resolve. The reason field (e.g., hard-bounce, invalid-email, unknown-user) helps classify the root cause. This data is standardized across Mailgun and can be mapped directly to your system.
3. Use an email verification tool like bulk email list cleaning to cross-validate any address flagged as permanently failed. This step ensures you’re not removing valid addresses due to temporary misclassification. Email List Validation’s accuracy rate—validated through real-world delivery testing—helps minimize false positives.
4. Automatically remove permanently invalid addresses from your list within 24 hours. Delayed cleanup hurts deliverability. According to Return Path’s deliverability benchmarks, consistently high bounce rates (>0.5%) correlate with inbox placement drops and blacklisting.
5. Log every decision—address, timestamp, reason, verification result—for audit and compliance. This supports GDPR, CAN-SPAM, and other regulatory requirements. Keep these logs accessible and timestamped to demonstrate due diligence.

Why this matters for deliverability

Permanent bounces degrade sender reputation. ISPs like Gmail and Outlook monitor bounce patterns closely. A single persistent invalid address may not break your reputation—but thousands of them do. Regular hygiene based on clear, actionable signals from your ESP (like Mailgun) is a standard practice.

Even if Mailgun identifies a bounce as permanent, relying solely on its judgment isn’t enough. Some addresses may be transiently blocked, or the error might be misreported. Cross-validating with a specialist tool—such as the real-time verification API—adds a layer of confidence. It’s not about replacing Mailgun’s data; it’s about reducing the risk of misclassification.

For teams using Mailgun with bulk sends, automation is not optional. Manual review is unsustainable at scale. The moment a bounced address is confirmed as invalid, it should be removed. That’s the rule for maintaining trust with inbox providers and avoiding throttling or filtering.

For more on how to test email deliverability and monitor real inbox placement, see inbox-placement testing.

A reference table of common Mailgun bounce subtypes and their implications

You need to parse Mailgun delivery responses for permanent bounce subtypes to clean your list, reduce bounces, and protect sender reputation. Subtypes like userunknown or no-mailbox indicate invalid addresses and should be removed instantly. Others, like blocked or rejected, may signal broader delivery issues requiring deeper checks. A clear understanding of each subtype’s meaning prevents over-cleaning or missed opportunities. For context, Mailgun’s official documentation outlines these subtypes as part of their delivery status feedback, which is aligned with industry standards (see Mailgun’s webhooks guide).

Permanent bounce subtypes and your response strategy

Not all bounces are equal. Some represent dead ends; others point to temporary or system-level issues. When analyzing feedback from Mailgun, focus on subtypes that signal permanent failures. You shouldn’t retry or keep these addresses in your list.

Using tools that parse and act on these subtypes at scale can improve email deliverability. Our bulk verification tool integrates with delivery platforms like Mailgun and identifies these subtypes before you send, so you’re not blindsiding your list with hard bounces. For real-time handling, our API gives you immediate feedback on individual addresses, allowing you to filter out problematic ones on the fly.

Why real-time verification outperforms post-send bounce parsing

You can’t fix a delivery failure after the email has already bounced. Parsing Mailgun’s delivery responses for permanent subtypes like "550 5.1.1" or "550 5.2.1" only tells you what went wrong after the damage is done—your sender reputation is already strained, your inbox placement suffers, and resources are wasted. Real-time verification stops invalid addresses before they ever reach the inbox, cutting bounce rates at the source. With Email List Validation’s 98.9% accuracy, you catch permanent failures before sending, not after.

Bounces happen too late to prevent harm

Post-send bounce parsing is reactive, not preventive. When Mailgun returns a permanent bounce—like “550 5.1.1 User unknown”—the message has already been processed by the recipient’s server. That means your sending IP was used, your sender reputation took a hit, and you’ve lost a delivery slot with no way to recover.

According to RFC 3463, permanent bounce codes like 550 are meant to indicate definitive failures. But waiting to act on them means you're playing catch-up with every failed delivery. Even a single bounce can trigger rate-limiting or temporary blocklists at major providers.

Prevention beats recovery every time

Real-time verification doesn’t wait for a bounce. It checks the address against SMTP, MX, and domain-level checks—in real time—before it ever leaves your system. Validity, role accounts, disposable domains, and catch-all traps are caught before your campaign even runs.

With Email List Validation, you’re not just reacting to bounces. You’re stopping them before they occur. The 98.9% accuracy rate means you keep legitimate addresses while eliminating invalid ones, with minimal false positives. That translates to better sender reputation, higher inbox placement, and fewer wasted sends.

For teams using Mailgun, this means fewer support tickets, less time troubleshooting delivery issues, and more predictable results. Instead of parsing bounce responses in real time—where you’re already behind—verify your list before you send. Use the real-time email verification API to integrate validation directly into your workflow, and turn your inbox placement into a predictable metric instead of a guessing game.

Use Email List Validation to proactively clean your list and reduce Mailgun bounce rates

You can reduce Mailgun’s permanent bounce rate by filtering out invalid and risky email addresses before sending. Run your list through Email List Validation to catch dead, malformed, or high-risk addresses before they hit your Mailgun outbound queue. This prevents bounces from corrupt or unreachable addresses, which hurt deliverability and can trigger blacklisting.

Step-by-step cleanup process

1. Upload your list to Email List Validation for bulk verification. The tool checks syntax, domain existence, and mailbox response logic—including whether the address is likely to reject mail (like a role address or catch-all). This runs fast, even on 10,000+ addresses.
2. Review the results immediately. You’ll get clear labels: valid, invalid, risky, or catch-all. Invalid addresses should be removed—these are dead ends. Risky ones (like temporary or role-based emails) often lead to bounces or low engagement and should be treated with caution.
3. Filter out invalid and risky addresses before sending through Mailgun. Removing these reduces your send volume of unreliable recipients, which reduces bounce rates and helps preserve sender reputation. According to Return Path’s (now Validity) research, sending to invalid addresses increases the chance of being flagged as spam by inbox providers.
4. Monitor the impact. After cleanup, send your campaign through Mailgun and track bounce types. You should see a sharp drop in permanent bounces—especially 5xx errors from MX servers or blocked domain responses. Cleaner lists improve inbox placement and long-term deliverability.
5. Use the in-app AI assistant to understand why certain addresses were flagged. Ask “Why is this address risky?” and get a clear explanation—like “It uses a temporary domain” or “It’s a role account like admin@ or postmaster@.” This builds internal knowledge and improves future list hygiene.

Why this works

Email List Validation uses real-time SMTP checks and advanced heuristics to detect common delivery issues before they happen. Unlike simple syntax checks, it identifies addresses that will likely bounce due to role accounts, disposable domains, or greylisting policies. You’ll catch issues that aren’t caught by Mailgun’s own pre-send diagnostics.

For real-time validation in your app or workflow, try the real-time verification API. For larger cleanups or regular audits, use bulk email list cleaning. With no credit expiration and 100 free verifications to start, testing is risk-free.

The bottom line: accurate parsing leads to better deliverability

Mailgun’s bounce subtypes provide precise signals about why an email failed. Ignoring these details treats all bounces as equivalent, which harms sender reputation and inbox placement.

Without distinguishing between permanent errors like invalid syntax or blocked domains, your system may continue sending to addresses that will never receive mail. This increases hard bounce rates and triggers filtering systems.

Proactive hygiene beats reactive cleanup

• Parse Mailgun’s delivery responses to identify permanent subtypes early.
• Flag invalid or unresponsive addresses before they harm your sending reputation.
• Integrate verification into your workflow to act before messages are sent.

Keep reading

• Bounce management: hard bounces, soft bounces and bounce rate (complete guide)
• Tools That Verify Emails and Warn About 554 5.7.1 Spam Score Threshold
• How to Fix 552 5.2.2 Size-Based Bounce in Bulk Email Validation
• Email List Hygiene Tool That Reduces 421 4.7.2 SMTP Risk
• Spam Scoring Causes 554 5.7.10 in SendGrid? How to Fix It

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

Frequently asked questions

What does Mailgun's 'permanent' bounce mean?

It means the email address is permanently unreachable, either because it doesn't exist or the domain rejects delivery permanently.

How do I find the bounce subtype in Mailgun's webhook?

Check the 'reason' field in the inbound webhook payload. Subtypes like 'userunknown' or 'no-mailbox' indicate permanent failures.

Can a 'mailboxfull' bounce be temporary?

Yes. A mailboxfull bounce is usually temporary. Reattempting later may succeed, but repeated instances suggest the address may be invalid.

Does Email List Validation support Mailgun integration?

Yes. You can use it to clean lists before sending via Mailgun, reducing bounce rates and improving inbox placement.

How accurate is Email List Validation’s real-time API?

It achieves 98.9% accuracy in detecting valid, invalid, catch-all, and risky email addresses.

Can I verify a list of 10,000 emails in bulk?

Yes. Our bulk verification tool handles large lists and returns results in minutes.

Do purchased credits expire in Email List Validation?

No. Every credit you buy never expires, so you can use them at any time.

What’s the difference between a 'catch-all' and a 'risky' email address?

A catch-all accepts all emails; it’s not a real person. A risky address has high chance of being invalid or unengaged.

How does real-time verification prevent spam traps?

By identifying invalid and non-existent addresses before sending, it reduces the risk of hitting spam traps.

What happens if I don’t clean my Mailgun bounce list?

Your sender reputation suffers, leading to higher spam filtering, lower inbox placement, and potential blacklisting.

Can I use Email List Validation with Mailchimp or Klaviyo?

Yes. The tool integrates with Mailchimp, HubSpot, Klaviyo, and SendGrid to clean lists before campaigns.

Is there a free way to test Email List Validation?

Yes. You get 100 free verifications to start, with no time limit on your credits.