Email Verification API with Configurable Bounce Code Mapping to Categories

Why is SMTP bounce code mapping essential for list hygiene?

You send an email. It bounces. You log in, check the error, and mark it as "failed." But what if that bounce code tells you something far more specific than just "failed"? What if it reveals whether the address is permanently invalid, temporarily overwhelmed, or even intentionally blocked by a recipient’s server?

Without mapping SMTP bounce codes to clear business categories — like 'invalid', 'suppressed', 'rate-limited', or 'temporary' — your team treats every bounce as the same. You’re left scrubbing clean addresses, resending to unreachable ones, and risking your sender reputation all while chasing a phantom list hygiene.

An email verification API with configurable bounce code mapping turns raw error codes into actionable decisions. Each bounce isn’t just a failure — it’s a signal. A well-configured API translates the technical language of SMTP into precise, filterable categories so you can clean your list in real time, reduce waste, and keep deliverability healthy.

Key takeaways

• SMTP bounce codes identify specific delivery failure reasons, from temporary outages to permanently invalid addresses.
• Without mapping codes to business categories, teams waste sends on addresses that can’t be reached, harming sender reputation.
• An email verification API with configurable bounce code mapping enables automatic filtering of invalid, suppressed, and rate-limited addresses based on real-time delivery feedback.

How does MailTester’s email verification API handle configurable bounce code mapping?

When you use MailTester’s real-time verification API, you receive detailed SMTP response codes for every address tested—like 550 (user unknown), 551 (user not local), or 421 (temporarily unavailable)—and these are automatically mapped to standardized verdicts such as 'invalid', 'catch-all', or 'risky'. You can override these defaults to match your internal workflows, delivery rules, or suppression logic. For example, you can treat a 551 as 'catch-all' if your system sees it as non-fatal, or mark a 554 response as 'blocked' for immediate suppression.

SMTP codes are mapped—then you decide what they mean

Every SMTP error code has a precise meaning defined in RFC 5321 and RFC 5322, but how you act on them depends on your use case. MailTester captures these codes exactly as received. By default, we map them to intuitive categories—like 550 to 'invalid' and 450 to 'temporary'—so you get a clear initial verdict. But since not all systems treat the same code the same way, we let you redefine these mappings.

Let’s say your system treats 551 (user not local) as a sign a user might still be active, even if they’re not at the current domain. Instead of marking it as 'invalid', you can reclassify it as 'catch-all'. Or if your email gateway blocks a high-volume sender and returns 554, you can set that to 'blocked' in your system to prevent future attempts. This mapping layer sits between raw SMTP data and your application logic.

The ability to reconfigure mappings ensures your inbox placement and send decisions reflect actual business behavior—not just technical standards. This reduces false positives, improves deliverability, and aligns your verification with your actual email strategy.

Because these mappings are configurable per request via the API, you don’t need to update a global rule—just apply the right logic per batch or per audience segment. It’s especially helpful when working with different domains, countries, or delivery platforms that each have unique thresholds.

Want to test this in action? Try it live with our real-time verification API—you’ll see the response codes, the default verdicts, and the option to override them on the fly. No hard limits on usage, and you get 100 free verifications to start.

What does 'configurable bounce code mapping' actually mean in practice?

You aren’t locked into a vendor’s rigid definition of what a bounce code means. With a configurable email verification API, you decide how each SMTP response code (like 550 or 4xx) maps to categories like “hard bounce,” “soft bounce,” or “risky.” This means your system reflects your actual delivery conditions, not someone else’s assumptions.

Why your system should define the rules

SMTP bounce codes aren’t universally agreed on. A 450 response might mean “try again later” in one platform, but indicate a full mailbox in another. What one team calls a temporary failure, another treats as a blocked address. Your delivery process, audience, and infrastructure shape how you interpret these codes. You shouldn’t have to adapt your logic to a tool’s fixed taxonomy.

Real-world impact of custom mapping

Let’s say 421 means “too many connections” from a specific mail server. In a high-volume campaign, that code might signal a need to throttle sending. In a smaller, less frequent send, it might be a false alarm. With configurable mapping, you can assign 421 to “risky” if it affects your deliverability strategy, or to “soft” if you're okay with retrying. The choice is yours — no hardcoded rules.

MailTester gives you full control through API parameters or dashboard settings. You can specify which SMTP codes belong to which categories, like hard bounce, soft bounce, or invalid address. This ensures your data pipeline aligns with how your team defines success and risk. For example, you can treat a 553 (invalid mailbox) as hard, but map a 552 (quota exceeded) as soft — even if the vendor might treat them the same.

Understanding these codes is foundational. The IETF’s RFC 5321 details SMTP response codes, but it doesn’t prescribe business meaning — only technical intent. Actual use depends on context. Tools that don’t let you configure this mapping force you into a one-size-fits-all model that drifts from real performance. With MailTester, you define the meaning, not the other way around.

This level of control prevents wasted effort on invalid addresses and helps preserve sender reputation. It’s especially valuable when managing multiple domains, segmented lists, or different delivery platforms. You’re not just verifying email addresses — you’re aligning your system with real-world sending behavior and infrastructure realities. Learn how it works in practice via our email verification API.

How does configurable mapping reduce false positives in list cleaning?

Generic email verification tools often treat all 550 SMTP errors the same—marking them as invalid—when in reality, some 550 responses indicate a catch-all inbox or a role account that can still accept mail. This one-size-fits-all approach leads to false positives: valid addresses get purged from your list, shrinking your audience and hurting engagement. With configurable bounce code mapping, you can define your own rules—like classifying a 550 error as “catch-all” if the domain is known to accept mail for unknown users—so only truly undeliverable addresses get flagged. This preserves active contacts while still catching real failures.

Why default mapping causes over-cleaning

Most tools assume any 550 response means the address doesn’t exist. That’s reasonable in theory, but in practice, many domains use catch-all configurations to capture mail for any user, even if they don’t exist. Sending to these addresses often works—especially with role accounts like admin@ or sales@. If your verification system marks these as invalid, you’re removing potentially active contacts, reducing list size by up to 20% in some cases.

Let’s be clear: not all 550s are equal. Some mean the user doesn’t exist. Others mean the system will accept mail but not confirm the user. Without configurable mapping, you can’t distinguish between them. This leads to aggressive list cleanup that kills engagement. According to RFC 6522, many 550 responses are used to prevent address harvesting—so their interpretation depends on context, not just the code.

How configurability fixes the problem

You can now set rules in your email verification API to override default behavior. For example: “If the domain has a catch-all policy (confirmed via MX or DNS lookup), treat 550 as ‘catch-all’ instead of ‘invalid.’” This allows valid sends to proceed, while still filtering out domains that genuinely reject mail. It’s especially helpful for B2B and outreach campaigns where role accounts are common.

MailTester’s email verification API supports this by letting you map SMTP status codes to custom categories. You define the rule, not the tool. The result? Fewer false negatives, higher deliverability, and more reliable list hygiene without over-cleaning. You’re not just removing bad addresses—you’re preserving ones that still matter.

What are the most common SMTP bounce codes and their typical meanings?

You're dealing with a hard bounce when you see a 550 — the recipient address doesn’t exist. A 551 means the user isn’t local, often pointing to a catch-all setup. Temporary issues like 421 (service down) or 450 (mailbox busy) usually resolve themselves. A 554 means your message was blocked, commonly due to spam filters or blacklists. 552 indicates the message is too large, especially when sending big attachments. These codes help sort bounces into actionable categories. For real-time validation and custom bounce mapping, see how MailTester’s verification API helps you map these codes to your internal workflows.

Bounce Code Reference Table

Why Mapping Bounce Codes Matters

Not all bounces are equal. A 450 or 421 might mean your message gets through after a retry. But a 550 or 554 is permanent — and those should be removed from your list immediately. The real power comes when you map these codes to named categories: “invalid”, “catch-all”, “temporary”, or “blocked”. This turns raw SMTP data into a system you can act on. Tools like MailTester’s email verification API let you define these mappings yourself — so you can tailor your suppression logic to your use case.

Understanding the difference between 550 and 551 is key. A 550 means the address is dead. A 551 points to a catch-all. But catch-alls can look valid — which is why verifying at scale is essential. According to RFC 5321, 550 codes are definitive and should not be retried. Similarly, 554 is often due to sender reputation or content filtering — not address validity. The real risk comes when you treat catch-alls as valid and send to them anyway, wasting bandwidth and hurting sender reputation.

How to build a custom bounce code mapping strategy

You can create a bounce code mapping strategy by first aligning it to your business goals—like reducing false positives or avoiding blacklists—then auditing your current bounce logs, classifying each SMTP response code (e.g., 550 = invalid) into meaningful categories, tagging 4xx codes as retryable, and using MailTester’s API or dashboard to apply and maintain your custom rules. Update the mapping quarterly or after infrastructure changes.

Start with your goals

Let’s be clear: you’re not verifying emails to "clean up your list"—you’re building a signal system. Do you want to block every invalid address, or avoid suppressing valid users who got a temporary bounce? Your answer shapes how you interpret codes like 550 or 450. If deliverability is top priority, you might treat 551 (user not local) as retryable, not invalid. If you're wary of blacklists, you’ll want to flag and investigate 5xx codes immediately.

1. Review your ESP or SMTP logs to map real-world bounces. Look at logs from the past 90 days. Identify the most common 5xx codes (permanent failures), 4xx codes (temporary), and any anomalies. These are your real data points—no assumption, no generalization.
2. Map each code to a category based on your infrastructure and policies. For example, 550 usually means "no such user," but if you use catch-all domains, that code doesn't always mean invalid—some users may be in a queue. In that case, 550 should map to "risky" or "possible catch-all" rather than "invalid." Always cross-reference RFC 5321 for standard SMTP response semantics.
3. Tag 4xx codes as 'retryable'—never suppress them as permanent errors. Codes like 450 (mailbox unavailable) or 421 (service not available) often indicate temporary issues. Suppressing these as "invalid" leads to false positives and hurt deliverability. Let them be handled by your send retry logic instead.
4. Apply your mapping using MailTester’s API or dashboard. If you're building a system that validates emails before sending, use the email verification API to enforce your custom logic. You can define what 551 means for you—whether it’s "invalid," "risky," or "invalid unless verified." The API supports full configuration.
5. Review and update the mapping quarterly or after major changes. Infrastructure shifts, new ESPs, or changes in email policies can alter bounce behavior. A quarterly audit ensures your mapping stays accurate. Use MailTester’s inbox placement tester to validate that your changes improve deliverability.

Keep your strategy honest

Just because a code exists doesn’t mean it’s universal. A 550 on one server may mean "user not found," on another, "mailing list disabled." Your mapping must reflect your actual sender setup, not textbook definitions. Always validate your rules against real delivery outcomes. The goal isn’t perfection—it’s consistency and reliability.

How does configurable mapping integrate with Mailchimp, HubSpot, and SendGrid?

You can map SMTP bounce codes to custom categories—like "catch-all," "rate-limited," or "temporarily unavailable"—using MailTester’s email verification API, then sync those verdicts directly into Mailchimp, HubSpot, or SendGrid. Once configured, every new verification run automatically updates your CRM or email platform with the mapped status, enabling precise tagging and targeted workflows without manual intervention.

Syncing mapped verdicts with your platform

When you run a bulk verification via MailTester’s API, the results don’t just return raw data—they arrive already translated into your chosen categories. If your system sends email through Mailchimp, HubSpot, or SendGrid, those mapped labels sync in real time. This means a contact flagged as "catch-all" in the verification report instantly gets tagged with that status in your platform, so you don’t need to write scripts or import CSVs after the fact.

Let’s say you use HubSpot. You can define a custom property, like “Verification Status,” and map it to MailTester’s bounce code categories. Once set up, every contact verified through MailTester gets that property updated—no more guessing why a send failed. This enables clean, automated workflows: skip re-engagement campaigns for suppressed addresses, or retry only temporarily unavailable ones.

Why customization matters in real workflows

Not all bounces are equal. A “4xx” error may mean a temporary issue—like over-quota limits—while a “5xx” is likely permanent. Without mapping, you’re stuck with generic labels. With MailTester’s configurable API, you define what each code means for your business. This is especially useful when setting up re-engagement rules: you can automatically exclude permanently bounced addresses, while rescheduling campaigns for rate-limited or transient failures.

For example, a 421 response from an SMTP server indicates temporary unavailability. Without mapping, your system might treat it as a hard bounce. But with configuration, you can tag it as "temporarily unavailable" and trigger a retry after 48 hours. This reduces false positives and keeps your sender reputation intact.

Configurable mapping isn’t just a feature—it’s a foundational element of reliable deliverability. Industry-standard tools like RFC 6522 define bounce codes, but how you act on them is up to you. MailTester gives you the control to align those codes with your business logic. Whether you're running campaigns in Mailchimp or managing leads in HubSpot, your system reflects the truth of each address’s status—without guesswork.

What happens when you don’t map bounce codes properly?

Without proper bounce code mapping, your system treats all bounces the same—flagging temporary glitches as permanent failures, suppressing valid addresses, and inflating hard bounce rates. This erodes sender reputation, increases the risk of blacklisting, and hides real issues like outdated emails or spam traps. You lose control of list hygiene and deliverability.

Here’s what breaks when bounce codes aren’t mapped correctly:

• You suppress valid addresses by mistaking transient failures (like rate limiting) for hard bounces—reducing your audience size unnecessarily.
• Temporary failures (e.g., 4xx codes like 421 or 451) get misclassified as permanent (5xx), which harms sender reputation over time by repeatedly marking addresses as dead when they’re not.
• You lose insight into real delivery problems: without categorizing bounce codes, you can’t tell if you’re hitting spam traps, sending to outdated addresses, or exceeding ISP rate limits.
• Hard bounce rates rise artificially because temporary issues aren’t filtered out properly—making your list look dirtier than it is and increasing the odds of being flagged by ISPs like Gmail or Yahoo.
• Over time, consistent misclassification can trigger auto-blocks from major providers, especially when your domain’s sending behavior appears inconsistent or abusive to their filtering systems.

Why proper mapping matters beyond the basics

Your email verification API should interpret bounce codes not just as success or failure, but as signals. A 450 error? That’s a temporary server issue—retry later. A 550 with “user unknown”? That’s a hard bounce. Let’s map them correctly.

Certain providers, like AWS SES and SendGrid, use standardized SMTP response codes—these are defined in RFC 5321 and RFC 6520. When you map them to clear categories (temporarily unavailable, permanent failure, spam trap, etc.), you align your system with industry-standard practices. That’s not theoretical: it’s how large-scale senders maintain high inbox placement.

The consequence of getting it wrong isn’t just a few missed deliveries. It’s degraded sender reputation, higher spam complaints, and harder-to-debug deliverability issues. You need to know why an email failed—not just that it did.

MailTester’s email verification API includes configurable bounce code mapping so you can define how each code affects your list hygiene and sending strategy. Whether you're building your own system or integrating with HubSpot, Klaviyo, or SendGrid, you get precise control over how bounces are classified and acted on.

How MailTester’s 98.9% accuracy supports effective bounce code mapping

You need accurate bounce code interpretation to properly segment hard and soft bounces, but most tools only guess. MailTester achieves 98.9% accuracy by validating each address via real SMTP sessions, not just rules-of-thumb. This means the underlying SMTP response codes—like 550 for non-existent users or 451 for temporary failures—are captured exactly as the mail server delivers them. With that foundation, your bounce code mapping isn’t based on guesswork, but on real-world behavior.

Real SMTP sessions ensure accurate code capture

Let’s be clear: an email isn’t invalid just because it doesn’t exist—it’s invalid because the server said so. MailTester doesn’t rely on database lookups or syntax checks alone. Instead, we establish a real connection to the mail server for every address, mimicking how your sending platform would connect during a real send. This includes reading the raw SMTP response codes after each step of the handshake. It’s the only way to get the true server-level signal.

Many low-accuracy tools use heuristics—patterns they’ve observed and guessed are reliable. But those patterns fail when servers respond differently, or when a catch-all domain returns a 250 instead of a 550. In practice, that means you might mislabel a hard bounce as soft, or wrongly flag a valid address as risky. That’s not just a data noise problem—it’s a deliverability risk.

Configurable mapping only works with trustworthy input

Even with full configuration options for what a 450 means to your system, the system must start with correct data. If your tool misreads a 550 as a temporary error, you’ll end up retrying failed deliveries. That harms sender reputation. Over time, ISPs notice repeated retries and block your IP.

As documented by the IETF’s SMTP specification, the exact response codes matter—not just the general meaning. For example, 550 means permanent rejection; 451 means a temporary issue. Accurate interpretation requires real SMTP interaction, not inference.

That’s why MailTester’s verification API—used by teams checking thousands of addresses in real time—delivers reliable code data. You can map codes to your own delivery rules, confident they reflect actual server behavior. If you’re building a high-volume send, this reliability prevents wasted sends, improves inbox placement, and avoids reputation damage.

Try accurate verification before you map your bounces. See how it works: check your list in real time with our API.

What are the best practices for maintaining bounce code mappings over time?

You should review and update your bounce code mappings after every major campaign, ESP switch, or significant change in your email workflow. Bounce codes evolve—domains change policies, ESPs reclassify errors, and new blocklists emerge. Without regular review, your automation may misclassify valid bounces as invalid, leading to delivery issues or blacklisting. Use real-world feedback from inbox placement tests to validate your mappings and keep a documented log of changes with clear business reasoning.

Keep mappings sharp with real feedback

• After launching a new campaign or switching ESPs, revalidate your bounce code mappings. Even small changes in delivery settings can alter how receiving systems respond.
• Monitor shifts in domain behavior—some domains that once accepted temporary errors (like 450) now reject them outright. This change impacts your delivery rate and bounce classification accuracy.
• Run inbox placement tests with MailTester’s inbox placement tool to verify whether your mapped bounces align with actual delivery outcomes. Real-world results are the only reliable benchmark.
• Use the MailTester API to test and validate the accuracy of your mappings during integration phases or when handling large volumes.

Document, track, and scale with confidence

• Keep a change log for every update to your bounce code mappings. Include the date, reason (e.g., “ESP switch from SendGrid to Amazon SES”), and the new classification.
• Share this log with your team during onboarding or audits. It ensures consistency across roles and avoids misinterpretations during troubleshooting.
• Review your mappings quarterly or whenever you add a new sender domain, ESP, or delivery channel—this prevents drift from real-world behavior.
• Consider RFC 3463 (SMTP diagnostics) as a baseline reference for standard bounce codes. While not all providers follow it strictly, it helps in understanding core classifications.
• For deeper insights, check how large senders manage routing via reports from Spamhaus or MxToolbox—they highlight common patterns in email delivery failure.

Clean your list with precision — not guesswork

Email verification isn’t about just filtering out bad addresses. It’s about understanding why they failed—whether it’s a typo, a rejected domain, or a temporary block.

With MailTester’s email verification API with configurable bounce code mapping to categories, you translate technical SMTP responses into actionable business insights. No more guesswork on hard bounces, soft bounces, or role accounts.

Reduce wasted sends, improve inbox placement, and protect sender reputation—all from a single API call. The data flows directly into your workflow with clear, custom-defined categories.

Sources

• Since May 5, 2025, Microsoft Outlook requires SPF, DKIM, and DMARC from domains sending 5,000+ emails per day, rejecting non-compliant mail outright at the SMTP level with error 550 5.7.515. — Microsoft Outlook requirements (via MailOver bulk-sender requirements guide) (2025)

Keep reading

• Bounce codes and SMTP errors explained (complete guide)
• Email Deliverability: When to Permanently Delete Hard Bounce Emails
• Customizable Soft Bounce Rules in Email Deliverability Tools
• Email Verification for Salesforce to Avoid 550 5.7.1 Spam Body Detection
• Integrate Email Verification to Avoid 550 5.7.1 Feedback Loop Mismatch

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

Frequently asked questions

Can I change how MailTester categorizes bounce codes after sending a batch?

Yes. You can adjust the mapping in the dashboard or via the API before processing future batches. Historical data retains its original categorization, but new verifications follow the updated rules.

Does MailTester support custom code mapping for 4xx or 5xx errors?

Yes. Any SMTP response code can be mapped to a custom category. You define the mapping based on your delivery system’s behavior and business logic.

How does this affect my deliverability?

Properly mapped bounce codes help avoid over-suppression and reduce hard bounce rates, both of which improve sender reputation with ISPs and ESPs.

Can I map multiple codes to one category?

Yes. You can group multiple SMTP codes (like 550 and 551) into a single logical category such as 'invalid' or 'catch-all' based on your system's needs.

Is the API integration easy with existing CRM systems?

Yes. MailTester integrates with Mailchimp, HubSpot, Klaviyo, and SendGrid. The API supports standard request/response patterns, making it simple to sync mapped verdicts.

Are there any limits to the number of custom mappings I can create?

No. You can define an unlimited number of custom mappings per domain or campaign, allowing granular control across different sender environments.

Can I use the mapping to skip re-verification of certain addresses?

Yes. Once you confirm a code’s meaning (e.g., 450 is retryable), you can build logic to avoid re-verifying those addresses until a set time or campaign triggers a refresh.

How does MailTester handle greylisting or temporary delays?

It detects 4xx replies from greylisting and classifies them as 'temporary' by default, so they don’t get marked as hard bounces. You can adjust this behavior in settings.

Can I test my mapping before applying it to my full list?

Yes. Use the real-time API with a small sample of addresses to validate how your custom mappings affect the verdicts before bulk processing.

Why should I care about bounce code mapping if I use a deliverability tool?

Because most deliverability tools only report bounces — they don't interpret them. You need your verification layer to understand the cause behind each bounce.

How accurate is the mapping process with MailTester?

MailTester’s accuracy is 98.9%, meaning it correctly identifies address validity and matches it to accurate SMTP codes. This ensures your mappings are based on real, reliable data.

Do I need to pay extra to use configurable bounce code mapping?

No. All API features, including custom bounce code mapping, are included in the standard plan. No additional charges or tier locks.