Skip to content

How Do I Reclassify a Bounce (Make a 5xx Transient Instead of Permanent)?

Sometimes a mailbox provider returns a 5xx that you would rather treat as temporary — a reputation or complaint block you expect to clear, where you want the message retried instead of hard-bounced. There are two ways to do it.

Option 1: classifier rules

Override the classification by adding a rule, loaded before the defaults, that maps the response to a transient class. The classifier matches against the normalized full response (status code plus content):

# custom_bounces.toml — loaded before iana.toml
[rules]
TransientFailure = [
  "blacklisted",
  "PolicyRelated",
]

kumo.configure_bounce_classifier {
  files = {
    '/opt/kumomta/etc/custom_bounces.toml', -- your overrides first
    '/opt/kumomta/share/bounce_classifier/iana.toml',
  },
}

Option 2: rewrite the response

Demote the SMTP response directly in policy, which keeps the message in retry:

kumo.on('smtp_client_rewrite_delivery_status', function(response, domain, ...)
  if response:find '550' and response:find 'blacklisted' then
    return 454 -- treat as transient
  end
end)

Rule precedence

If more than one rule matches, the rule from the file loaded first wins, so define your overrides before iana.toml. Prefer matching the meaningful phrase from the community bounces.toml rather than building everything from scratch.

Note

Connection-time failures (errors that occur before any per-message data is sent) are always treated as transient transport errors. KumoMTA cannot attribute them to a specific recipient.

There is no built-in validator for the classifier file. Lint the TOML, load it on one node, and watch for an acceptable rate of unclassified bounces before rolling it out.

See also