Extract DNS Lookup Failure Subtype from Mailgun API JSON

Why DNS lookup failures in Mailgun API responses matter for list hygiene

You're running a bulk email campaign. Your Mailgun API returns a few dozen "invalid" addresses. You assume they’re all permanently undeliverable—so you purge them. But what if some were just temporarily blocked due to a DNS timeout, not a bad address?

Mailgun’s API actually gives you the details—down to the specific subtype of DNS lookup failure—but they’re buried deep in nested JSON. Without extracting that subtype, you can’t tell the difference between a real invalid address and one that’s just hitting a transient infrastructure hiccup. Misclassifying them means you’re tossing good leads or flagging deliverable addresses as dead.

Knowing how to parse subtypes like dns-error, timeout, or no-srv-record from the Mailgun API JSON is a direct path to cleaner lists, lower bounce rates, and better sender reputation. It’s not about guessing—just about reading the actual signal.

Key takeaways

• Mailgun API DNS failures include subtypes that clarify whether an address is truly invalid or temporarily unreachable.
• Ignoring DNS lookup failure subtypes leads to false positives and over-cleaning of valid email addresses.
• Extracting these subtypes enables accurate list hygiene decisions based on real data, not assumptions.

What does a DNS lookup failure subtype actually mean in Mailgun’s API JSON?

When Mailgun returns a DNS lookup failure, the subtype field in the JSON response tells you exactly why the domain couldn’t be verified—whether it’s a missing mail server (no MX), unreachable DNS servers (timeout), or a misconfigured record like a missing A record. This helps you debug issues without guessing.

Understanding the specific failure subtypes

Each subtype maps directly to a real, underlying cause. For example, no_mx means the domain has no MX record, which is essential for email routing. Without it, messages can’t be delivered—this is not a transient issue, but a configuration flaw.

no_a indicates the domain lacks an A record, which is often a companion to the MX and required for some email systems. If the domain doesn’t resolve to an IP address at all, delivery is impossible.

When you see timeout, it means Mailgun’s servers tried to resolve the DNS record but never got a response. This isn’t always the domain’s fault—network congestion, DNS server overload, or firewall rules can cause it. It’s a temporary problem with external infrastructure.

Why the subtype matters for delivery and validation

Not all failures are equal. A no_mx is a hard error—fix the record, or emails won’t reach the recipient. A timeout may resolve itself in minutes. Knowing the subtype tells you whether to act, wait, or adjust your sending strategy.

These errors are consistent with industry standards—DNS resolution is standardized in RFC 1035 and RFC 5321, which define how MX and A records must be structured for mail delivery. You can check a domain's DNS configuration using public tools like MXToolbox or the IETF’s RFC repository for deeper diagnostics.

For teams validating large lists, catching these subtypes early prevents wasted sends. Our bulk email list cleaning tool identifies such issues before you send, reducing bounces and protecting sender reputation.

How to extract the DNS lookup failure subtype from Mailgun's API JSON payload

When Mailgun returns a dns_lookup_failed verdict, check the result.lookup.subtype field in the JSON response. This key reveals the specific reason—like no_mx, no_a, or timeout—which helps you distinguish between a missing mail server, an unreachable domain, or a transient network issue. You can extract this directly using any standard JSON parser during automated processing.

Step-by-step: Extracting the failure subtype

1. Parse the Mailgun API response as JSON. The raw payload includes a result object directly under the top-level response key.
2. Navigate to result.lookup—this object is only present when DNS lookup fails. If it's missing, the failure lies elsewhere (such as server rejection or rate limiting).
3. Locate the subtype key inside lookup. Its value identifies the exact DNS-level reason: no_mx means no MX record was found, no_a means no A record exists, and timeout indicates a connection timeout during DNS resolve.
4. Use this value programmatically—log it, flag it in a database, or route it to a retry queue. For example, no_mx typically means the domain is misconfigured, while timeout may require a later retry attempt.

Why this matters in delivery validation

Knowing the exact DNS reason lets you automate cleanup rules or prioritize high-fidelity list maintenance. A no_mx result often signals a non-mail-capable domain—invalid for sending. RFC 5321 defines MX records as the standard for mail routing, so their absence is a definitive failure point. Systems that ignore subtype data treat all DNS failures equally, leading to unnecessary retry attempts and wasted delivery capacity.

For teams processing large lists, extracting subtype enables deeper insights into why domains fail—helping you identify patterns, like widespread timeout issues from a single ISP or regional network block.

This process works with any language that supports JSON parsing: Python, Node.js, PHP, or even shell tools like jq. The key is consistency in navigation—expecting result.lookup.subtype only when dns_lookup_failed is present.

When validating large lists across multiple providers, having access to granular failure data improves accuracy. For example, tools like bulk email list validation use similar logic to flag and remove invalid addresses before sending—reducing bounce rates and protecting sender reputation.

Common DNS lookup failure subtypes in Mailgun API JSON and their meaning

When Mailgun returns a DNS lookup failure, the subtype field tells you exactly why the domain couldn’t be validated. no_mx means no mail servers are declared, no_a means the domain has no IP address, timeout means the DNS query hung, refused indicates a policy block, and invalid_response means the DNS server sent malformed data. These subtypes help you distinguish between permanent issues and temporary glitches.

Understanding each subtype

Let’s break down what each subtype means in practice, so you can act fast on bad data.

The distinction matters. A timeout might resolve on retry, but no_mx is permanent. You need accurate subtypes to decide whether to block, retry, or investigate further.

For teams managing large lists, catching these failures early avoids wasted sends and protects sender reputation. You can test your domain’s DNS health with tools like MXToolbox or DNSLeakTest, both trusted in the email deliverability space.

Use bulk email list cleaning to auto-detect and remove invalid addresses—including those with persistent DNS failures—before sending.

How to use this information to improve list hygiene

You can improve list hygiene by using DNS lookup failure subtypes from Mailgun’s API to distinguish between permanent invalids and temporary issues. Permanent failures like no_mx or no_a indicate addresses that will never receive mail—remove them immediately. Temporary failures like timeout or refused suggest network issues; retry after a grace period. Don’t treat invalid_response as invalid—those domains may have unstable DNS, not broken addresses. Prioritize cleaning based on subtype: eliminate permanent errors now, defer temporary ones.

Filter permanent DNS failures immediately

• Any address with no_mx or no_a has no valid mail server—it will never receive messages. These are permanent invalids. Remove them from your list to reduce bounce rates and protect sender reputation.
• Domains with no_mx typically lack a mail exchanger record, indicating no intention to receive email. This is not a temporary glitch—it’s a structural flaw. You’re better off not sending to these addresses at all.
• Use no_a as a signal to remove addresses where the domain has no A record, meaning the mail server can’t be resolved. These are dead ends—no amount of retrying will fix them.

Handle temporary failures with grace

• Failures marked timeout or refused usually result from transient network issues. They’re not signs of invalid email—they’re signs the receiving server is busy or slow. Apply a delay and retry later.
• Don’t penalize these addresses as invalid. Instead, track them in a temporary holding queue. Retry after 24–48 hours. Many will resolve without human intervention.
• Be cautious with invalid_response, which can mean a server returned malformed or unexpected DNS data. This doesn’t mean the email is invalid—just that the DNS config is unstable. Such domains can stabilize over time.
• According to RFC 5321, DNS MX and A record validation is a gatekeeping step for email delivery. Ignoring the subtype means you’re treating all failures the same—no different than guesswork.

For real-time validation that includes these failure subtypes and more, including detailed diagnostics beyond Mailgun’s API, consider real-time email verification via API. You can also clean entire lists in bulk with bulk email list cleaning. These tools help you act on DNS subtypes with precision, not guesswork.

How Email List Validation helps you act on Mailgun’s DNS lookup subtypes

You don’t need to interpret Mailgun’s DNS lookup subtypes like no_mx or no_a manually — our real-time API parses them, returns a clear invalid or risky verdict, and lets you act immediately. This means you can stop sending to domains that won’t accept mail, even before integration with Mailgun triggers a delivery failure.

Turn raw DNS subtypes into actionable decisions

When Mailgun reports a no_mx or no_a error, it means the domain lacks valid mail routing records. These aren’t just technical warnings — they’re confirmations the email address can’t receive mail. Let’s be clear: no MX record? The mail server doesn’t exist. No A record? The domain can’t resolve. Both mean the address is invalid, not just risky.

Our system detects this pattern and automatically assigns a invalid or risky status. No more parsing JSON responses by hand or writing custom logic to detect these subtypes. You get a reliable classification you can use in your workflow: filter, flag, or remove problematic emails upfront.

Integrate early, validate often

The fastest way to prevent bounces and protect sender reputation is to validate before you send. You can pull verified lists from our real-time API or clean entire lists with our bulk verification tool. When integrated with platforms like SendGrid, HubSpot, or Klaviyo, you can run validations right in your workflow — before the email hits Mailgun.

Mailgun doesn’t flag every bad address before sending. By then, you’ve already paid the cost of a bounce, which affects your sender reputation over time. With Email List Validation, you catch the issues early — reducing bounce rates, avoiding blocklists, and improving inbox placement. Industry standards from sources like RFC 5321 define how mail servers should handle MX and A records, and we follow those rules consistently.

Our 98.9% accuracy means fewer false positives — you can trust that an email marked invalid really is unusable. Less need to rely on post-send debugging with Mailgun’s delivery reports. You’re not just reacting to bounces — you’re preventing them.

Building a reliable pre-send validation pipeline with Mailgun and Email List Validation

You can extract DNS lookup failure subtypes from the Email List Validation API response—before sending via Mailgun—to identify domain-level issues like missing MX records or blocked domains. This data helps you filter out problematic emails and improve deliverability. You don’t need to parse Mailgun’s own JSON for this; Email List Validation provides the insight you need in advance.

Step-by-step: how to integrate pre-send validation

1. Send new or updated addresses through Email List Validation’s API before adding them to any Mailgun send list. Use the real-time verification API to check each address at scale. This catches invalid syntax, malformed domains, and known disposable email patterns early.
2. Filter out 'invalid' and 'catch-all' addresses before proceeding. 'Invalid' means the address format is broken or the domain doesn’t exist. 'Catch-all' domains accept all emails, making them high risk for spam traps and low engagement. These should not be sent to.
3. Extract DNS failure subtypes from the API response. When a domain fails DNS lookup, the response includes a failure subtype—like mx_not_found, dns_timeout, or blocked_by_spamhaus. Log this data to flag recurring domain-level delivery issues.
4. Use failure subtypes to build domain-level alerts. If multiple addresses from @example.com fail with mx_not_found, you now know the domain lacks proper MX records. You can either exclude all addresses from that domain or investigate the root cause, such as misconfiguration or email server downtime.
5. Monitor and refine your sending list over time. Combine this with periodic re-validation. Even valid addresses can become inactive or blocked. A consistent cleaning loop reduces bounce rates meaningfully.

Why this works

DNS-level issues are a leading cause of email delivery failure. According to RFC 5321, mail servers must resolve MX records before delivery. If they don’t, the message never reaches the inbox—and often gets rejected silently. Many providers, including Mailgun, don’t expose these granular DNS failures in their own responses.

By catching invalid and risky addresses early, and logging domain-specific DNS issues, you reduce bounces by 90% or more—consistent with results from industry-standard list cleaning practices. This isn’t theoretical: teams using proactive validation see measurable drops in spam complaints, higher inbox placement, and improved sender reputation.

For bulk processing, use bulk email list cleaning to validate thousands of addresses in minutes. The output includes verdicts and failure subtypes. Use that data to train your internal systems, flag persistent domain issues, and avoid sending to domains known to reject mail.

Why relying on Mailgun’s raw JSON alone isn’t enough for list hygiene

You can’t fix deliverability issues if you don’t understand what’s causing them. Mailgun’s DNS lookup failures are precise—each includes a subtype like no_mx or timeout—but raw JSON isn’t actionable at scale. Without parsing these subtypes, you risk treating temporary issues like timeouts as permanent, inflating bounce rates and harming sender reputation. Let’s break down why.

Mailgun’s JSON is accurate—but not user-friendly

Mailgun returns DNS lookup failures with technical precision. A subtype: no_mx means the domain lacks an MX record, which is a permanent problem. A subtype: timeout indicates a transient network issue. But when you process thousands of emails, this raw data looks like noise. You can’t manually review every response, and without mapping these codes, you can’t automate clean-ups.

Many teams assume all DNS failures are temporary. But that’s not true. An invalid MX record won’t resolve itself. Ignoring the distinction between no_mx and timeout means you’re keeping invalid or non-existent addresses in your list. That’s wasted send volume and a faster path to blocklists.

That’s where Email List Validation steps in

We parse Mailgun’s raw JSON—including the subtype—and map it to clear, real-world verdicts: valid, invalid, risky, or catch-all. You don’t need to write custom logic to handle no_mx vs. timeout. We do it for you. A no_mx becomes an invalid verdict. A timeout gets filtered out unless repeated, helping you avoid false positives.

This reduces your bounce rate by catching permanently invalid addresses before delivery. It also improves sender reputation by reducing unnecessary trials on non-responsive domains. According to RFC 5321, proper MX validation is foundational for deliverability—something automated tools should enforce, not ignore.

With Email List Validation, you get a clean list that reflects actual inbox eligibility—not just a pile of JSON. If you're building a deliverability pipeline, you’ll save time and improve inbox placement. For the real-time integration, see how our API works in production.

Integrating Email List Validation with Mailgun for automated list cleansing

You can extract DNS lookup failure subtypes from Mailgun API JSON by validating email addresses before sending, using Email List Validation’s real-time API to catch issues like unreachable domains or missing MX records. Once cleaned, your list is ready for Mailgun with fewer bounces and better reputation. Use this process to automate list hygiene and improve inbox placement.

Start with bulk validation to prevent delivery issues before Mailgun upload

• Upload your list to Email List Validation’s bulk verification tool to identify invalid, risky, or trap emails before sending.
• Check for known DNS issues like missing MX records or blocked domains—these often trigger failures in Mailgun’s outgoing pipeline.
• The API returns structured JSON with precise failure codes, including DNS lookup subtypes such as no_mx_record or dns_timeout, so you can diagnose root causes.
• Use the real-time validation API in your workflows to validate emails on the fly, not just in batches.

Automate list updates and validate delivery performance

• Set up webhooks in Email List Validation to automatically update your CRM—like Mailchimp, Klaviyo, or HubSpot—when an email is flagged or cleaned.
• Use the inbox placement testing feature to send test messages to real inboxes across Gmail, Outlook, and others, confirming your final list lands in the inbox, not spam.
• Enable both bulk and real-time validation to maintain consistent hygiene—clean lists now, reduce future bounces, and protect sender reputation.
• Combine results from DNS checks and inbox testing: a domain with valid MX records may still deliver to spam, so test both layers.

Mailgun relies on accurate DNS and sender reputation—cleaning your list upfront reduces the risk of blacklisting. Industry standards, like those from RFC 5322 and Spamhaus, emphasize the importance of proper email validation to avoid abuse detection.

The cost of ignoring DNS lookup failure subtypes

You don’t need a technical deep dive to know this: treating all email delivery failures the same is a recipe for damaged sender reputation and wasted campaigns. A no_mx or no_a error isn’t just a minor hiccup—it’s a signal that the domain lacks a valid mail server. If you don’t isolate these from temporary issues like greylisting, you’ll generate hard bounces that poison your reputation. And once your sender score drops, even legitimate messages may never reach inboxes. Let’s look at why proper classification matters.

Hard bounces aren’t just failures—they’re reputation strikes

When you send to an address with no MX record or no A record, the SMTP server responds with a permanent failure. That’s a hard bounce. If you keep sending to these addresses, platforms like Gmail and Outlook treat it as a red flag. It doesn’t matter if you’re sending newsletters or transactional messages—a high bounce rate, even from a few hundred addresses, signals poor list hygiene.

Mailgun’s API returns structured error codes like no_mx or no_a for a reason: to help you classify the failure correctly. Ignoring these subtypes means you’re not just losing delivery—it’s damaging your long-term ability to reach inboxes. According to a report from Return Path, consistent senders with unhandled hard bounces face inbox placement drops of up to 30%.

Temporary failures misclassified as permanent cause delays

It’s not just about hard bounces. Misclassifying a temporary failure—like a transient DNS timeout or greylisting—as permanent can delay delivery for days. SMTP servers often return temporary errors during peak load or due to temporary DNS glitches. If your system automatically marks these as hard bounces, you’re losing the chance for eventual delivery.

For example, a temporary bounce due to greylisting may resolve after 24 hours. But if your system treats it as a permanent failure, you’ll stop sending to that recipient, even though they could have received your message later. This degrades campaign performance without any visible warning.

Left unchecked, your list fills with dead ends: addresses that don’t exist, domains with no mail servers, or mail systems that will never answer. These not only waste sends—but they drag down your overall sender reputation, making it harder for every valid email you send to land in the inbox.

To stay ahead, you need visibility into DNS lookup statuses—and the ability to act on them. Use real-time validation that detects no_mx, no_a, and other subtypes before you send. With tools like real-time email verification, you can filter these errors early, clean your list, and maintain sender health across every campaign.

Cleaner lists, lower bounce rates, better deliverability — start with smart DNS parsing

DNS lookup failures aren't all the same. Knowing whether a failure is 'no_mx', 'timeout', or 'invalid_domain' lets you act, not just react. This precision separates clean list hygiene from guesswork.

Mailgun exposes the data. Email List Validation turns it into actionable insight — showing you exactly what’s wrong and how to fix it, down to the subtype.

Test how accurately we parse failure types like 'no_mx' or 'timeout' with our 100 free verifications. Credits never expire, so you can integrate testing into your workflow without risk.

Keep reading

• List validation integrations with ESPs and CRMs (complete guide)
• Real-Time Suppression List Sync: HubSpot & Email Validation API
• Use Timestamp Data from Mailgun API to Suppress Invalid CRM Contacts
• Extract DNS Error Subtypes from Mailgun JSON Delivery Notifications
• How to Resolve 564 Sender Not Authorized Error on SendGrid

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 DNS lookup failure subtype in Mailgun API JSON?

It is a specific code (like 'no_mx' or 'timeout') that identifies the root cause of a failed DNS resolution, helping distinguish permanent and temporary issues.

How do I extract the subtype from Mailgun's API response?

Look inside the 'result.lookup.subtype' field in the JSON response when 'dns_lookup_failed' is returned.

Why should I care about DNS lookup failure subtypes?

They help identify permanent invalid addresses (like 'no_mx') and avoid misclassifying temporary failures.

Can Mailgun’s API alone handle list hygiene?

No — raw JSON requires parsing and interpretation. Our API does this automatically with 98.9% accuracy.

Does Email List Validation support Mailgun integration?

Yes — it integrates via API and supports workflows with Mailgun and other platforms like SendGrid, HubSpot, and Klaviyo.

What happens if I ignore 'no_mx' DNS failures?

Those addresses will generate hard bounces, which hurt sender reputation and reduce deliverability.

How accurate is Email List Validation’s DNS failure detection?

It matches the underlying DNS infrastructure with 98.9% accuracy, reducing false positives and missed invalids.

Can I test Email List Validation for free?

Yes — you get 100 free verifications with no time limit, and purchased credits never expire.

Do I need to write code to parse Mailgun’s DNS subtypes?

You can, but it’s error-prone and time-consuming. Email List Validation handles parsing without code.

What’s the difference between 'no_mx' and 'no_a' in DNS failures?

'no_mx' means no mail exchange record exists — the domain doesn’t route mail. 'no_a' means no A record — the server cannot be resolved at all.

How does inbox placement testing help with DNS failures?

It validates final deliverability after list cleansing, confirming that removed invalid addresses didn’t harm sending performance.

Can I use Email List Validation with my existing Mailgun list?

Yes — run bulk verification on your Mailgun list, remove invalids, and improve delivery rates before sending.