Mailgun Reject Reason Mapping to Bounce Subcodes for Real-Time Verification

Why Mailgun's bounce subcodes matter for email list hygiene

You’ve cleaned your list, verified every address, and still see bounces. Why? Because Mailgun’s rejection reasons don’t always match the standard SMTP or RFC 3463 definitions. A subcode that looks like a temporary issue might actually mean the address is permanently invalid.

Without a clear mapping between Mailgun’s reject reasons and actual deliverability risk, you could keep sending to dead addresses or mistakenly discard valid ones. That’s not just inefficient—it damages sender reputation, lowers inbox placement, and hurts deliverability over time.

Understanding Mailgun’s bounce subcodes—especially how they diverge from industry standards—is essential for accurate real-time email verification. It turns guesswork into precision, and prevents your list from being poisoned by silent failures.

Key takeaways

• Mailgun’s bounce subcodes often deviate from RFC 3463 standards, requiring custom mapping for accurate validation.
• Mistaking a fatal bounce (like "mailbox unavailable") for a temporary one can result in retaining permanently invalid addresses, harming sender reputation.
• Without accurate rejection reason mapping, real-time verification risks either over-filtering valid emails or under-cleaning invalid ones—both degrade deliverability.

What does 'Mailgun reject reason' actually mean in real-time verification?

Mailgun’s reject reasons are SMTP-level responses from recipient servers that tell you exactly why an email was rejected during delivery attempts. Each reason—like 'address unavailable' or 'user unknown'—is mapped to a subcode that provides granular insight into the failure, helping you pinpoint whether an email is invalid, temporarily blocked, or permanently undeliverable. These subcodes are critical for accurate real-time verification, especially when integrating with platforms like Mailgun.

How reject reasons reflect actual delivery outcomes

When Mailgun attempts to deliver an email, it engages in an SMTP handshake with the recipient server. If the server rejects the transaction, it returns a reason (e.g., 'mailbox full') and a subcode (like 552 or 550), which the system uses to categorize the failure. These codes aren’t arbitrary—they follow standards defined in SMTP RFCs, such as RFC 5321, which define the format and meaning of server responses.

For example, a 'user unknown' (550 5.1.1) indicates the email address doesn’t exist—this is a hard bounce. A 'mailbox full' (552 5.2.3) is a temporary failure, meaning the recipient’s inbox is full but could accept mail later. These distinctions matter: you don’t want to treat a temporary issue the same as a permanent one.

Why mapping subcodes is essential for accuracy

Without mapping reject reasons to subcodes, you’re left guessing. A general 'rejected' status could mean anything from a typo to a firewall block. But when you parse the subcode, you gain context: is it a syntax error? A blacklisted sender? A catch-all policy restriction?

Real-time verification systems—like the one we offer via our real-time email verification API—use these mappings to classify addresses accurately. They don’t just say "invalid"; they tell you, “This address is unknown,” or “This domain rejects incoming mail.” That level of detail lets you clean lists precisely and act on deliverability signals with confidence.

Some services surface only high-level failures. But we go deeper. Our system captures the full SMTP transaction, maps each reject reason to its subcode, and translates that into actionable verdicts: valid, invalid, risky, catch-all, or temporary. This fidelity ensures your email sends reach real inboxes—not just servers that say "yes" on paper.

How Mailgun reject reasons map to RFC 3463 bounce subcodes

Mailgun’s reject reasons often align with standardized RFC 3463 bounce subcodes—like 5.1.1 for unknown user or 4.2.1 for routing failure—but not always cleanly. Some reasons, such as "blocked by policy," don’t map to a single subcode and require contextual analysis. When subcodes are missing or ambiguous, verification systems must interpret server responses, delivery attempt behavior, and SMTP error codes to determine the most accurate classification.

Matching Reject Reasons to Standard Subcodes

Let’s look at a few common Mailgun reasons and how they align with RFC 3463. "User unknown" typically maps to 5.1.1, which indicates the recipient doesn’t exist. "Mailbox full" corresponds to 5.2.2, signaling a temporary delivery failure due to capacity. These are straightforward mappings that follow industry-standard definitions.

But not all reasons are so clear. "Blocked by policy" might point to a sender reputation issue, greylisting, or even spam filtering. This doesn’t fit neatly into one subcode. Similarly, "spam detected" may stem from content filtering or blacklisted IPs, but the underlying cause isn’t always reflected in the subcode. The RFC itself acknowledges this challenge: a subcode alone doesn’t capture the full story—context matters.

When Subcodes Fall Short: Context is Key

When a bounce lacks a clear subcode—or the subcode is ambiguous—you need more than just the reason. A real-time verification system must analyze multiple signals: the precise SMTP response code (e.g., 550 vs 552), whether the failure occurred early or late in the SMTP transaction, and whether the same address consistently fails across multiple attempts.

For example, a recurring 550 error after the RCPT TO command points strongly to invalid or non-existent recipients. A series of 4xx temporary failures may suggest temporary issues like a full mailbox or greylisting. These patterns help validate or refine the subcode assignment, even when the original message doesn’t include one.

Industry-standard practices, like those outlined in RFC 3463, provide the foundation for consistency. But real-world delivery systems—including Mailgun—add layers of policy and filtering that extend beyond the RFC. That’s why tools that combine SMTP validation with behavioral analysis outperform those relying solely on static mappings.

For deeper insight into how real-time verification systems resolve these ambiguities, you can explore our bulk verification process: clean large email lists with context-aware validation.

How Email List Validation maps Mailgun reject reasons to subcodes

When Mailgun rejects an email, our system captures the exact rejection reason and maps it to the appropriate SMTP subcode using RFC 3463 standards and historical delivery patterns. For example, "user unknown" becomes subcode 5.1.1 (hard bounce), while "mailbox full" is treated as 4.2.1 (temporary) unless repeated, triggering a risk flag. We evaluate "rejected by policy" contextually—only if the policy is known to be permanent (e.g., enforced sender blocklist) do we treat it as a hard failure.

Mapping logic rooted in real-world SMTP behavior

Mailgun’s rejection messages are cryptic by design. "User unknown" might mean the mailbox doesn’t exist, but it can also signal temporary filtering. Our system cross-references each reason against RFC 3463’s standardized list of delivery status codes and real-time patterns from billions of verified sends. This ensures we don't misclassify a temporary issue—like a spam filter delay—as a permanent bounce.

For instance, a "mailbox full" error is initially tagged as 4.2.1, but repeated failures over 24–48 hours shift the status to 5.2.2 (mailbox unavailable), which we flag as potentially invalid. The same holds for "rejected by policy"—if the policy is a known block based on sender reputation or IP, we map it to 5.7.1 (policy rejection). But if it's a temporary rule (e.g., rate limiting), we treat it as 4.2.1 unless confirmed otherwise.

Why accuracy matters in real-time verification

Incorrect subcode mapping leads to poor list hygiene. A mistaken hard bounce might drop valid users; a missed temporary error can clog your send queue. Our engine avoids this by combining layered validation: immediate RFC compliance checks with historical delivery trends. This reduces false positives and ensures only truly invalid addresses are removed.

Unlike some tools that treat all Mailgun rejections as static failures, we apply context—timing, repetition, and sender reputation—before assigning a verdict. This level of nuance is why our real-time email verification API achieves 98.9% accuracy across domains, including high-risk sectors with strict filtering.

Test email addresses instantly with our API to see how we map rejection reasons into accurate subcodes, or use our bulk verification tool to clean entire lists with the same logic. Both services are powered by the same engine, ensuring consistent, real-world accuracy.

The difference between a hard bounce and a soft bounce in real-time verification

Hard bounces (like 5.1.1 or 5.1.2) mean the email address is permanently invalid—no such user exists, or the domain is unreachable. Soft bounces (like 4.2.1, 4.2.2, or 4.3.1) signal temporary issues: full inbox, server timeouts, or message size limits. Real-time verification catches both, but only hard bounces are treated as outright invalid. Soft bounces get a closer look—they’re risky if repeated, even if they resolve later.

Hard bounces: when delivery fails forever

Hard bounces happen when an address is malformed, doesn’t exist, or has been permanently blocked. Codes like 5.1.1 (user unknown) or 5.1.2 (mailbox unavailable) are clear signals: this address is dead space. If you’re sending to a hard bounce, the message will never reach the inbox. Ignoring them inflates your bounce rate, can trigger sender reputation penalties, and eats up your deliverability credits.

According to RFC 3463, these 5xx codes represent permanent delivery failures. They are the definitive "stop" signal from an email system. Tools like Mailgun return them precisely, but only when the server has confirmed the failure. Real-time verification catches them before you send—so you never waste a delivery attempt.

Soft bounces: temporary glitches with long-term risk

Soft bounces (4xx codes) indicate issues that might resolve within hours or days. A 4.2.1 means the mailbox is full. A 4.2.2 shows a transient server error. A 4.3.1 points to a message that’s too large. These aren’t errors in your email; they’re issues on the recipient’s end.

But here’s where it gets tricky: repeated soft bounces over time suggest a persistent problem. A mailbox stuck at full capacity, for example, may mean the user isn’t checking mail—so you’re sending to an inactive address. That’s still a high-risk recipient. Our system flags such addresses as "risky" or "invalid" if soft bounces recur across multiple delivery attempts.

Let’s say you send to 1,000 contacts, and 7% get soft bounces due to full inboxes. If those same addresses keep bouncing, they’ll eventually become unreliable. Even if the error clears once, repeated failures damage sender reputation. Email List Validation applies consistent rules: if a soft bounce occurs multiple times, we treat it like a long-term signal that the address is no longer active.

This prevents ongoing delivery issues that harm inbox placement. You stay on good terms with providers like Gmail and Yahoo. See how it works: verify emails in real time and avoid delivery risks before you send.

How to interpret Mailgun's 'rejected by policy' — a common real-time verification challenge

When Mailgun returns "rejected by policy," it typically means the recipient domain blocked your message due to sender reputation, IP reputation, or content filters—commonly seen with strict inbound policies or high spam thresholds. This is often a soft bounce if it’s reputation-driven, but can be permanent if the domain outright blocks third-party senders. Without context, treating it as hard often leads to over-removal of valid addresses.

Why 'rejected by policy' isn’t always a hard failure

Mailgun’s policy rejections can reflect temporary issues like a sender’s IP being flagged for low engagement or outbound volume spikes. For example, if your IP recently had high bounce rates or was used in a past misconfiguration, many domains treat it as high-risk—even if your message is legitimate. This is a common scenario in shared sending environments.

Alternatively, some domains enforce strict sender policies—blocking emails from non-verified or non-internal sources entirely. These are permanent blocks, often used by corporate or institutional domains. The same rejection code applies to both cases, making automatic classification error-prone.

Distinguishing soft from hard failures with real-time data

Without historical sender data or domain-level signals, it’s easy to misclassify these rejections. A single "rejected by policy" response doesn’t tell you whether the address is genuinely invalid or just facing a transient block. That’s where deeper context matters.

Tools like Email List Validation use real-time and historical data—including sender reputation trends, domain-level sending behavior, and prior deliverability patterns—to evaluate if a policy rejection is likely temporary or permanent. For instance, if similar domains frequently accept mail from your IP but still return policy rejections, the issue is probably misaligned filtering, not a hard block. This reduces false negatives.

See how it works: verify emails in real time with confidence using signal-backed verdicts that go beyond basic syntax checks.

You can test these patterns with deliverability tools like inbox-placement testing to see how your messages fare across real inboxes—with no guesswork.

For broader context, the RFC 5321 standard defines message transmission behavior, while spam filtering practices are well-documented in resources like those from the Spamhaus Project—which tracks sender reputation, a key factor in policy-based rejections.

How to use reject reason mapping to improve list hygiene in bulk verification

You can significantly improve list hygiene by mapping Mailgun's reject reasons to specific bounce subcodes during bulk verification. Use these mappings to filter out permanently invalid addresses, flag problematic ones like "mailbox full" or "message too large," and preemptively block high-risk emails before sending. This reduces bounces, protects sender reputation, and improves inbox placement over time.

Filter hard bounces across multiple attempts

• Identify email addresses that consistently return hard bounce subcodes (like 5.1.1 or 5.2.1) across multiple verification attempts. These are almost certainly invalid and should be removed.
• Use your verification tool to flag entries with repeated failure codes — even a single hard bounce may warrant removal, but consistency confirms it’s not a temporary issue.
• Prevent sending to these addresses by integrating real-time validation into your workflow, so new entries never make it to the send queue.

Monitor recurring soft bounce signals

• Pay attention to consistent "mailbox full" (5.2.2) or "message too large" (5.3.4) responses. These often indicate outdated accounts or misconfigured mail servers.
• These addresses may remain valid for months, but if they’re consistently rejecting messages, they reduce your delivery rate and can harm sender reputation over time.
• Keep these on a watchlist rather than outright deleting them — they might become valid again. But don’t send marketing content to them until cleared.
• When you’re preparing campaigns, avoid using any address that returns the same soft bounce code three times in a row.

Mailgun’s bounce subcodes map directly to real SMTP-level responses. Understanding these codes — from SMTP 5xx errors to delivery agent rejections — gives you deeper insight than a simple "valid" or "invalid" label. The IETF’s RFC 5321 and RFC 5322 define the core SMTP error model, and tools built on this standard allow you to correlate response codes with user behavior.

Let’s say you’re using the real-time email verification API to validate addresses before adding them to a campaign. You can check for bounce subcodes programmatically in your workflow, blocking any address that returns a persistent 5.1.1 or 5.2.2. This is faster and more accurate than relying only on the initial delivery result.

Consistent rejection mapping doesn’t eliminate all bounces — some domains use greylisting or temporary filters — but it eliminates the majority of predictable failures. You’re not just cleaning up bad data; you’re training your system to respect actual delivery constraints.

Real-time verification API: How we turn Mailgun subcodes into actionable list cleanup

You don’t need to decode Mailgun’s raw bounce codes. Our API ingests Mailgun’s rejection details—like 5.1.1 or 5.7.1—and maps them to plain, actionable verdicts: Valid, Invalid, Catch-all, or Risky. This means you clean your list with precision, not guesswork. Every result is backed by real-time checks across SMTP, MX, and domain policies, so your deliverability improves without extra friction.

From Mailgun errors to clear actions

Mailgun’s subcodes tell you what went wrong, but not what to do. We turn that noise into a decision matrix you can act on immediately. For example, a 5.1.1 (invalid address) becomes "Invalid"—remove it. A 4.2.1 (temporary failure) becomes "Risky"—monitor, don’t send.

Understanding the difference between a hard bounce (like 5.1.1) and a temporary one (like 4.2.1) is key to maintaining sender reputation. A high rate of 4xx codes can trigger throttling or blocklists—even if all addresses eventually work. SMTP standards define these codes precisely, but they don’t tell you what to do next.

Using our real-time email verification API means you get consistent, standardized verdicts—no more parsing logs or guessing. You process hundreds of addresses in seconds, get clean data instantly, and integrate directly into your workflow. Whether you're sending via Mailgun or another platform, the outcome is the same: fewer bounces, higher inbox placement, and cleaner data.

Why relying solely on Mailgun’s reject reason is insufficient for list hygiene

You can’t trust Mailgun’s internal reject reasons alone to clean your list. They’re not standardized across providers, don’t account for deliverability signals like spam filtering or engagement, and can’t distinguish between a deactivated account and a valid, inactive address. Without deeper verification—like DNS and SMTP checks—you risk treating borderline cases as valid, which hurts deliverability and inflates bounce rates.

Mailgun’s reasons are not universal

Mailgun’s reject codes reflect its own internal logic, not a shared industry standard. For example, a "rejected" status might mean a blocked domain on Mailgun, but the same address could be accepted by Gmail or Outlook. These signals don’t translate across providers, so relying on them as a universal truth leads to false assumptions about an address’s viability.

Even within Mailgun’s system, a single reason like “invalid email address” may mask multiple underlying causes—typos, role accounts, or temporary delivery issues—none of which can be disambiguated without full verification.

What’s missing? The full picture

Deliverability isn’t just about whether an email was accepted. It’s about whether it lands in the inbox, gets flagged as spam, or is ignored by the recipient. Mailgun’s reject reasons don’t show how an address behaves *after* it’s accepted. A valid address might still end up in spam if it’s a dormant or role-based account, or if your sender reputation is low. RFC 6521 defines the structure of SMTP bounce codes, but even those don’t capture real-world behaviors like engagement or unsubscribe rates.

For real list hygiene, you need to verify at the network level. That means checking DNS records, performing an actual SMTP handshake, and analyzing patterns like domain reputation and common typo risks. Only then can you tell if an address is truly valid, risky, or just temporary.

Let’s be clear: Mailgun’s rejection codes are a starting point, not a conclusion. True email accuracy comes from layered validation. Tools like bulk email list cleaning or real-time verification provide the depth you need—checking SMTP, DNS, and behavior patterns to prevent false positives and improve deliverability long-term.

How we integrate with Mailgun and other sending tools for real-time validation

You can validate email addresses in real time before sending by integrating our API directly with Mailgun via webhook or direct call. This avoids sending to invalid, risky, or undeliverable addresses, keeping your sender reputation intact. We support SendGrid, HubSpot, Klaviyo, and Mailchimp through native integrations, ensuring clean lists and high inbox placement across platforms. The result? Fewer bounces, lower spam complaints, and consistent deliverability — all without changing your current workflow.

Mailgun integration: real-time validation at scale

• Our API connects to Mailgun’s inbound or outbound webhook system to validate addresses instantly when they’re added to a campaign or collected from a form.
• Each email is checked against SMTP, MX, DNS, and role account rules in real time — no batch delays, no false positives.
• Mailgun’s bounce subcodes (like "550 5.1.1" or "554 5.7.1") are mapped to our internal verdicts — invalid, catch-all, risky, or valid — so you know exactly why an address failed.
• We return verified results immediately, allowing you to filter out invalid addresses before they hit your Mailgun queue.
• This mapping ensures you’re not just ignoring bounces, but acting on the real cause — whether it’s a typo, a blocked domain, or a greylisted server (as outlined in RFC 5321).

Extended platform support: unified validation workflow

• You get the same real-time checking across SendGrid, HubSpot, Klaviyo, and Mailchimp via pre-built integrations — no custom code required.
• Each integration maps bounce reasons from the provider to our standardized email verdicts, so your team sees consistent signals across tools.
• Validated addresses are pushed back into your workflow, so you’re always working with a clean list — directly in the platform where you send.
• For broader cleanup, you can also run bulk list validation on our platform to identify long-term hygiene issues.
• With our real-time API, you’re not just reactive — you’re building sender reputation from the start.

Conclusion: Map, verify, clean — turn Mailgun’s rejection data into actionable intelligence

Mailgun’s reject reasons provide a starting point, but they lack specificity. A single "reject" message can stem from a hard bounce, a temporary delay, or a deliverability block — without subcode context, you can’t tell which.

Real-time email verification with accurate subcode mapping turns ambiguous rejections into clear signals. You can now distinguish between permanent failures like invalid addresses and temporary issues like greylisting or rate limiting.

With this clarity, you clean your list proactively. Lower bounce rates. Better sender reputation. A system that doesn’t just report errors, but interprets them — so you make decisions based on data, not guesswork.

Keep reading

• Email marketing compliance: GDPR, CAN-SPAM, consent and unsubscribes (complete guide)
• Mailgun vs SendGrid Reputation Management for Indian Startups in 2025
• Automated Email Validation with Real-Time 450 4.2.0 Response Analysis for Security
• How to Troubleshoot 554 5.7.1 Spam Rejection Using Domain Monitoring
• Fix 554 Error 5.7.1 by Testing Email Deliverability Before Sending

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

Frequently asked questions

How does Email List Validation map Mailgun reject reasons to standard bounce subcodes?

We cross-reference Mailgun's reject reasons against RFC 3463 standards and real-time delivery behavior to assign accurate, consistent subcodes.

Can I trust Mailgun’s reject reasons to clean my email list?

No. Mailgun’s reasons lack standardization and context. Relying solely on them risks over-cleaning or under-cleaning your list.

What’s the difference between a hard and soft bounce in Mailgun?

Hard bounces (5.1.x) mean the address is invalid or unreachable. Soft bounces (4.x.x) are temporary issues like full inboxes or server timeouts.

How does real-time verification prevent hard bounces?

By validating addresses before sending, using SMTP checks, DNS records, and sender reputation signals to reject invalid or risky emails.

Does Email List Validation work with Mailgun’s API?

Yes. It integrates directly with Mailgun via webhook or API call to verify addresses in real time before delivery.

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

A catch-all domain accepts all incoming emails, even for non-existent users. These addresses are risky and often lead to spam complaints.

How accurate is Email List Validation’s verification process?

It achieves 98.9% accuracy by combining SMTP checks, DNS validation, and behavioral analysis across multiple delivery attempts.

Do purchased credits for Email List Validation expire?

No. Once purchased, credits never expire, giving you flexibility in managing bulk verification across campaigns.

Can I integrate Email List Validation with HubSpot and Klaviyo?

Yes. The tool offers native integrations with HubSpot, Klaviyo, SendGrid, and Mailchimp to validate lists before sending.

Why do some soft bounces turn into invalid addresses?

Repeated soft bounces (e.g., mailbox full or message too large) indicate a long-term problem. We flag these as risky or invalid to prevent delivery issues.

What is the benefit of inbox-placement testing with Email List Validation?

It checks whether verified addresses actually land in the inbox, not just the spam folder, giving you true deliverability insight.

How does Email List Validation handle role account emails like info@ or support@?

It detects and flags role accounts as high risk due to low engagement and frequent forwarding, helping you avoid poor campaign performance.