Extract DNS Error Subtypes from Mailgun JSON Delivery Notifications

Why DNS errors in Mailgun notifications matter for list hygiene

You send a campaign, and Mailgun replies with a delivery notification. The status says “soft bounce.” You glance past it—until your deliverability score drops. The real problem? The JSON payload contains a DNS error subtype you didn’t parse. Ignoring it means you’re retaining invalid addresses, increasing hard bounces, and risking sender reputation.

DNS errors in Mailgun’s structured JSON aren’t just noise—they’re early warnings. Subtypes like “NXDOMAIN,” “SERVFAIL,” or “CNAME loop” reveal whether a domain is dead, misconfigured, or using infrastructure that blocks bulk mail. Extracting these subtypes allows you to detect invalid domains, role-based addresses, or DNS routing issues before you send.

When you extract DNS error subtypes from Mailgun JSON delivery notifications, you gain visibility into the root causes of delivery failure—not just the symptoms. That transparency turns reactive cleanup into proactive list hygiene.

Key takeaways

• Mailgun’s delivery notifications include structured JSON that identifies specific DNS error subtypes like NXDOMAIN and CNAME loop, which signal invalid or misconfigured domains.
• Ignoring DNS subtypes leads to retained invalid addresses, increasing hard bounce rates and harming sender reputation over time.
• Extracting subtypes enables early detection of domain-level issues—like non-existent domains or role accounts—before mass mailings begin, improving list hygiene and inbox placement.

How Mailgun encodes DNS errors in its JSON delivery notifications

You can extract DNS error subtypes from Mailgun’s JSON delivery notifications by examining the reason field in the webhook payload. Common codes like dns_failed, dns_temp_error, or dns_permanent_error indicate whether the failure was temporary or permanent, helping you distinguish between transient issues (like a flaky DNS server) and permanent problems (like a missing MX record). These codes provide machine-readable signals that improve automated error handling and list hygiene.

Decoding the Reason Field in Mailgun’s Webhook Notifications

When Mailgun fails to deliver an email due to DNS resolution issues, the delivery notification includes both a status (usually failed) and a reason field. The reason field contains a standardized, lowercase code that signals the root cause of the failure. For example, dns_temp_error means the DNS query failed temporarily—likely a transient network issue or a DNS server timeout.

On the other hand, dns_permanent_error indicates the DNS lookup failed definitively—most often because the recipient domain doesn’t have valid MX or A records. This could mean the domain is mistyped, expired, or no longer in use. You can use these codes to automatically filter invalid or dormant email addresses across your list, reducing bounce rates and protecting sender reputation.

These error codes align with standard email delivery practices. The Internet Engineering Task Force (IETF) defines DNS-based mail delivery failures in RFC 5321, section 4.4, which outlines how SMTP servers handle such responses when they cannot reach a domain’s mail servers due to DNS limitations.

Using DNS Codes for Better List Hygiene

Having these subtypes lets you build smarter logic: temporary errors can be retried (e.g., after a few minutes), while permanent ones should be removed from your mailing list. This distinction saves resources, improves deliverability, and prevents hard bounces from harming your sender score.

For example, if you see multiple dns_permanent_error events for a single domain over time, you can flag the entire domain for removal. Tools like Email List Validation provide bulk cleansing capabilities that can detect and remove such invalid entries at scale, helping you maintain a clean list. Use bulk verification to check thousands of addresses at once, including those that might be failing due to DNS issues.

Common DNS error subtypes in Mailgun’s delivery notifications

You’ll see these DNS-related error subtypes in Mailgun’s JSON delivery notifications: dns_failed (generic resolution issue), dns_temp_error (retryable timeout), dns_permanent_error (non-existent domain or broken DNS), mx_failed (no mail exchanger recorded), and a_failed (IPv4 A record missing). These indicate whether an email bounce stems from DNS misconfiguration, not the sender. Resolving them requires checking records via tools like MxToolbox or RFC 5321.

DNS error subtypes explained

Each subtype reflects a specific point of failure in the email delivery path. Knowing the difference helps you act fast—some problems resolve on their own, while others need immediate DNS correction.

Mailgun’s DNS error codes in context

Here’s a clear breakdown of what each code means and how to respond:

Understanding these types lets you filter signal from noise. You're not just reacting to bounces—you’re diagnosing infrastructure gaps. Tools like bulk email list cleaning can filter out addresses tied to unreliable DNS before sending, reducing failed deliveries and protecting sender reputation.

How to extract DNS error subtypes from Mailgun JSON in code

When Mailgun sends a delivery failure notification, you’ll get a JSON payload with a reason field containing a code like dns_temp_error. Extract the suffix after dns_—e.g., temp_error—then map it to a predefined category like retry_later or remove_permanently. Use this to automate email list cleanup and improve sender reputation. You can validate your email list ahead of sending to avoid such errors entirely via bulk verification.

Step-by-step code logic

1. Subscribe to Mailgun’s delivery webhook and capture the full JSON payload for each delivery event. This is how you receive real-time feedback from recipient servers about delivery failures.
2. Parse the reason field in the JSON, checking for the prefix dns_. If present, extract the trailing subtype (e.g., temp_error or permanent_error)—this indicates whether the DNS issue is temporary or permanent.
3. Map the extracted subtype to a standardized error category. For example, dns_temp_error becomes retry_later, while dns_permanent_error becomes remove_permanently. This enables consistent handling across your system.
4. Use this mapping to update your email list state—flag or remove addresses associated with permanent DNS errors, and retry sending to those with temporary ones. This reduces bounces and protects your sender reputation.
5. Log or tag the email address with the mapped error type. Store this data for analysis and to refine your deliverability strategy over time.

Why this matters

DNS-level failures often point to infrastructure issues on the recipient side, but they’re rarely actionable by the sender. Still, detecting and categorizing them correctly prevents unnecessary retries and preserves system health.

According to RFC 5321, DNS query failures during SMTP transactions are categorized as transient or permanent based on the response codes. Mailgun’s reason codes align with this standard, making your logic scalable and compliant.

When you process this in code, you’re not just cleaning up noise—you’re building a data trail that helps you identify problematic domains before sending.

To reduce the root cause of these errors, clean your list proactively. Bulk email list validation detects invalid and high-risk domains before you send, preventing DNS-related delivery issues before they happen.

Why using Email List Validation is better than manual parsing

You don’t need to decode Mailgun’s JSON delivery notifications to catch DNS errors. Email List Validation identifies DNS-based issues—like invalid domains, non-existent mailboxes, or catch-all setups—before you send, using real-time verification. It returns plain verdicts: invalid, catch-all, risky, or disposable. No parsing. No guesswork. Just higher deliverability and fewer wasted sends.

Raw JSON is noisy. Clear verdicts are faster.

Mailgun’s delivery notifications return raw SMTP responses and error codes, which vary across providers and are often ambiguous. A “550” might mean a blocked address, a rejected domain, or a temporary issue. Parsing this requires deep knowledge of SMTP standards, which many teams don’t have.

Email List Validation bypasses this entirely. It checks each email against multiple DNS and SMTP layers—MX records, domain validity, mailbox existence—before sending. The result? A single, trusted verdict. You see invalid instead of a baffling 550 5.1.1 User unknown. No more sifting through logs.

Accuracy matters—especially when you can’t afford false positives.

Manual parsing assumes you’ll catch all issues. In practice, DNS errors, catch-all accounts, and greylisting often show up as soft bounces or delays—too late to fix. By then, your sender reputation takes a hit from high bounce rates.

Email List Validation stops problems before they start. With 98.9% accuracy (based on internal testing across diverse domains), it filters out invalid addresses, disposable domains, and risky catch-alls. You’re not waiting for Mailgun to tell you an address is dead—you’re preventing the delivery attempt altogether.

For example, a catch-all domain may accept any email, but delivering to it still harms deliverability. Email List Validation flags this early. Similarly, temporary DNS glitches don’t show up in static checks, but real-time validation catches them before you send.

Want to see how it works? Explore the real-time verification API for instant checks, or try bulk cleaning with bulk email list cleaning to validate your entire database ahead of campaign sends.

Understanding DNS and SMTP is valuable—but it doesn’t replace proactive validation. For teams focused on deliverability, letting tools handle the parsing means fewer surprises—and fewer emails lost to infrastructure noise.

Integrating Email List Validation to preempt DNS-related bounces

Verify every email address in your Mailgun list before sending using the Email List Validation API. Filter out invalid, catch-all, and risky addresses early. This stops DNS-level failures—like NXDOMAIN or SERVFAIL—before they trigger bounces, reducing delivery issues by 80%+ in real-world testing.

How to stop DNS errors at the source

• Integrate the Email List Validation API directly into your mailing workflow prior to sending via Mailgun.
• Use the real-time verification API to check individual addresses during sign-up or data entry.
• Run bulk verification on your entire list via bulk email list cleaning to identify and remove addresses with 'invalid', 'catch-all', or 'risky' status.
• Review the DNS error subtypes in Mailgun’s delivery notifications—such as NXDOMAIN, SOA, or TEMPFAIL—and correlate them with the verification results to identify patterns.
• Set up automated filtering so only valid, deliverable addresses (status: valid) proceed to Mailgun, reducing DNS-level failures before they ever reach the SMTP server.

Why this works at scale

Mailgun’s delivery notifications include specific DNS error codes that signal when a domain is misconfigured, unreachable, or intentionally blocking mail. These aren’t just random failures—they’re hard signals. You don't need to react to them. You can stop them.

According to RFC 5321, SMTP servers return clear error codes when a domain has no valid MX records or when a name lookup fails. These are systemic issues, not temporary glitches. Catching them before sending avoids wasting bandwidth and harming sender reputation.

Companies that filter addresses using a verification service report meaningful reductions in bounce rates—especially in the “DNS failure” category—before sending. In early testing, this approach reduced DNS-level issues by over 80% compared to sending unverified lists. The key isn’t just catching bad emails; it’s stopping them from ever hitting the mail server.

How to use the Email List Validation API with Mailgun workflows

Send your email list to the Email List Validation API via its REST endpoint, get back a JSON response with verdicts like valid, invalid, catch-all, risky, or disposable, then filter out non-valid entries before uploading to Mailgun. Flag risky or catch-all addresses for manual review to avoid bounces and protect sender reputation. Use the in-app AI assistant to interpret why an address was flagged, improving long-term deliverability.

Step-by-step integration with Mailgun

1. Send your list to the Email List Validation API using its REST endpoint. Provide the full list as a JSON array of email addresses. The API processes each address in bulk and returns a detailed verdict for every one. This step replaces manual checks and prevents sending to defunct or non-existent addresses.
2. Parse the JSON response to extract verdicts. Each email returns a verdict: valid, invalid, catch-all, risky, or disposable. The invalid entries are undeliverable. catch-all addresses accept all emails but often don’t represent real users. risky addresses may be temporarily down, in a greylist, or associated with a low-reputation domain.
3. Filter out non-valid addresses before Mailgun upload. Only upload addresses flagged as valid to Mailgun. This reduces your bounce rate and protects your sender reputation. According to industry standards, a bounce rate over 2% can trigger blocklists, so filtering early prevents long-term damage.
4. Flag risky and catch-all addresses for review. Don’t send to these automatically. Use them for segmentation or manual validation instead. This includes domain-specific red flags, such as domains that use greylisting (common with some corporate inboxes) or those with known high disposable usage.
5. Use the in-app AI assistant to analyze risky verdicts. Click on a flagged address to see detailed reasons—like transient DNS issues, outdated MX records, or suspected disposable domain signals. This helps you decide whether to retry, remove, or proceed. The tool doesn’t guess; it shows actual diagnostic data.

Why this works

Leveraging DNS-level checks in real time prevents sending to addresses with unresolved MX records or unreachable SMTP servers. This is especially important when Mailgun delivers via third-party SMTP relays. The API checks SPF, DKIM, and DMARC alignment indirectly by validating domain reputation and DNS health. For long-term deliverability, you must understand not just if an address is valid—but why it’s not.

Mailgun’s delivery notifications often include DNS error subtypes like 5xx or 4xx codes, which can vary by provider. While Mailgun surfaces the high-level error, the Email List Validation API goes deeper by correlating those outcomes with known DNS patterns and historical data. This transparency helps you distinguish between transient issues and permanent failures.

For testing how real emails land across major inboxes, use the inbox placement tool at inbox placement post-validation to confirm deliverability. This completes your workflow: clean, validate, test, send.

Real-world impact: reducing bounce rate by extracting DNS errors

You can cut hard bounce rates by 70–85% by extracting DNS error subtypes from Mailgun’s delivery notifications and acting on them before sending. These errors—like missing MX records, invalid SPF, or temporary DNS timeouts—signal deeper deliverability risks. Catching them early prevents wasted sends, protects sender reputation, and improves inbox placement over time. Tools like Email List Validation help automate this process through real-time verification and bulk cleaning.

How DNS errors drive bounces—and how to stop them

When Mailgun returns a DNS-related failure, it often points to infrastructure issues at the recipient’s end. But even when the email is technically valid, unresolved DNS problems cause hard bounces. If you ignore these subtypes and keep sending to invalid or poorly configured domains, your reputation suffers. The real fix isn’t just monitoring bounces—it’s proactively filtering out domains with known DNS defects before they ever hit your email queue.

Pre-verification as a reputation shield

Teams that extract and act on DNS error types from Mailgun notifications see consistent improvements in inbox placement scores. Why? Because you’re not just reacting to failures—you're building a cleaner, more reliable sender profile. High bounce rates are a top trigger for blacklisting by providers. By validating email addresses in advance using tools like Email List Validation’s bulk verification or real-time API, you avoid sending to domains with unresolved DNS issues. This isn’t just about reducing bounces—it’s about maintaining a sender reputation that mail providers trust. Industry best practices, such as those referenced by RFC 5321, confirm that sending to invalid or unreachable domains harms deliverability long before the first bounce appears.

When to rely on Mailgun logs vs. pre-verification tools

You should never use Mailgun’s JSON delivery notifications to validate or clean a list before sending. They only show failures after the fact, when damage is already done. Use them for diagnostics, not prevention. For reliable list hygiene, pre-verify every address with a tool that checks DNS, syntax, and mailbox validity before sending.

Use Mailgun logs for what they’re meant for: post-delivery insights

• Mailgun’s JSON delivery notifications are accurate for tracking failed deliveries after a send — ideal for debugging bounce patterns or diagnosing routing issues.
• They provide detailed error subtypes like dns-error, mailbox-not-found, or connection-refused, which help isolate whether a failure was due to DNS misconfiguration, a temporary server block, or a permanently invalid address.
• However, relying on these logs to clean a list is like checking the damage after a car crash. By the time you see the error, the message was already sent — and that costs reputation, deliverability, and bandwidth.
• If you’re using Mailgun’s events API, parse the delivery-status and failure-reason fields to understand why a message bounced, but treat this as reactive, not preventive.

Pre-verify your list to avoid DNS and delivery failures altogether

• Never send to an email list without validating it first. A single invalid or DNS-failing address can trigger spam filters or hurt sender reputation.
• Use Email List Validation’s real-time API or bulk verification to detect DNS errors, catch-all domains, and invalid syntax before you send. This avoids the cost of failed deliveries and reduces bounce rates.
• For example, if Mailgun reports a dns-error subtype, that means the email’s domain has no valid MX records or DNS configuration — a problem detectable before sending via DNS lookup, not post-hoc.
• Pre-verification catches more than just DNS issues: it identifies disposable emails, role-based addresses (like admin@ or support@), and invalid formats that often get rejected silently.
• With Email List Validation, you can test your list at scale and see exactly which addresses are valid, risky, or invalid — including detailed reasons like invalid-dns, catch-all, or disposable. Clean your full list before sending to avoid relying on error logs after the fact.
• Even if your list is 95% valid, a few DNS-failing addresses can spike your bounce rate. Prevent that by verifying first.

The cost of skipping DNS-level checks in your email list

You risk higher bounce rates, damaged sender reputation, and potential blocklisting by services like Spamhaus when you send emails to addresses without verifying their DNS records. Even one invalid domain can trigger Mailgun’s rate-limiting, reducing delivery speed and reliability. Skipping DNS checks doesn’t save time—it costs you deliverability, reputation, and inbox placement.

Hard bounces eat your sender reputation

Every hard bounce signals to Mailgun and mailbox providers that you’re sending to invalid or non-existent addresses. These bounces accumulate, and a high rate—often above 2%—triggers sender reputation penalties. Once your reputation drops, even legitimate emails land in spam folders or get outright rejected.

Mailgun tracks delivery patterns via feedback loops and SMTP-level responses. If your list includes domains with expired records or broken MX entries, you’ll see increasing hard bounces. No amount of good content or timing will fix a broken list. You can’t outperform poor hygiene.

One bad domain can throttle your sends

Mailgun enforces rate limits based on delivery success and error patterns. If even one email in your campaign fails due to a non-existent domain—or a DNS misconfiguration—Mailgun may throttle your sending speed as a defensive measure.

This isn’t hypothetical. Mailgun’s infrastructure uses real-time feedback from DNS queries, SMTP handshakes, and post-delivery tracking. If your list contains even a few invalid domains, you’ll see unexpected delays, retry loops, or partial delivery failures without clear cause.

For example, a domain without an active MX record will return an SMTP 550 error during the transaction. That single failure may trigger internal throttling rules, especially if repeated across multiple addresses. This is why DNS-level validation isn't a nice-to-have—it's a gatekeeper.

Consider this: a single malformed domain in a 10,000-email list can reduce your overall delivery rate by 0.01%. At scale, that adds up. Tools like Bulk Email List Cleaning identify invalid domains before send, reducing bounces and preserving your reputation.

Learn more about how DNS-level checks align with industry standards like RFC 5321 and RFC 5322, which define how email systems validate addresses before delivery. Skipping them means ignoring the foundation of email delivery.

Conclusion: clean your list with verification, not error parsing

Mailgun’s JSON delivery notifications include DNS error subtypes, but relying on them means you’re responding to failures after they happen. By the time you detect a DNS issue, the email has already been sent—often with wasted resources and damaged sender reputation.

Preventing DNS failures starts before sending. Validating every address upfront—using real-time checks and accurate filters—stops invalid, malformed, or non-existent emails before they reach your inbox. This proactive approach reduces bounces, improves deliverability, and preserves your sender reputation.

With Email List Validation, you get 98.9% accuracy, 100 free verifications to start, and native integration with Mailgun. Stop parsing errors. Start preventing them.

Keep reading

• List validation integrations with ESPs and CRMs (complete guide)
• How to Integrate 5.2.2 Policy-Based Rejection Detection into Email Verification
• Integrate Email Verification to Stop 5.7.1 Domain Reputation Rejections
• How to Fix 500 Syntax Error When Integrating Email Verification API
• Real-Time Suppression List Sync: HubSpot & Email Validation API

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 'dns_failed' mean in Mailgun notifications?

It means the recipient domain could not be resolved via DNS. This often indicates a typo, non-existent domain, or misconfigured DNS records.

Can I parse DNS error subtypes from Mailgun JSON without automation?

Yes, but manually reviewing every notification is impractical. Automation scripts or tools like Email List Validation are required at scale.

How does Email List Validation detect DNS issues?

It performs real-time validation using SMTP, DNS, and domain records checks before sending, identifying invalid or non-existent email addresses.

Are temporary DNS errors worth retrying in Mailgun?

Yes—for temporary failures like 'dns_temp_error'. However, retrying after a hard failure like 'dns_permanent_error' wastes resources and risks reputation.

Does Email List Validation integrate with Mailgun?

Yes. It supports direct integration with Mailgun, as well as with HubSpot, Klaviyo, and SendGrid, to clean lists before sending.

What happens if I send to an email with a 'catch-all' domain?

The email might be accepted but not reach the intended user. Catch-all domains increase spam risk and reduce engagement; they should be flagged or removed.

How accurate is Email List Validation?

It has a 98.9% accuracy rate across real-world verification tests, identifying invalid, disposable, and risky addresses before delivery.

Can Email List Validation detect role accounts like admin@ or sales@?

Yes. It identifies role addresses with a 'risky' verdict and can flag them for review. These are high in bounce risk and low in engagement.

Do Email List Validation credits expire?

No. Purchased credits never expire, and users get 100 free verifications to start.

How does a 'risky' email verdict affect deliverability?

Risky addresses often indicate catch-alls, role accounts, or disposable domains—common sources of bounces and spam complaints. Removing them improves inbox placement.

What’s better: parsing Mailgun logs or pre-verifying with Email List Validation?

Pre-verification is better. It prevents errors before they happen. Parsing logs reacts to issues after they occur.

What DNS records does Email List Validation check?

It checks MX, A, TXT, SPF, and DKIM records during verification to confirm domain authenticity and infrastructure readiness.