Bounce categorization beyond hard and soft

Hard and soft are a coarse-grained taxonomy that obscures the correct remediation for each failure type. A mailbox-full bounce (452, 552) is a temporary capacity issue — retry in 24 hours. A content-blocked bounce (550 containing 'spam') means a campaign is triggering spam filters — retry will not help; the campaign content must change. A domain-not-found bounce means the sending domain itself is rejected — DMARC or IP reputation requires review. RFC3463 defines enhanced status codes specifically to enable this differentiation. Collapsing all bounces to hard/soft forces engineering to run manual queries against diagnostic messages to recover information that should be structured in the data model.

Parse diagnostic codes at webhook ingestion time and store the sub-category alongside the raw bounce event. Route each category to the appropriate handler:

type BounceSubCategory =
  | 'address_not_found' | 'mailbox_full'
  | 'content_blocked' | 'policy_rejected'
  | 'domain_not_found' | 'unknown'

export function categorizeBounce(
  code: number,
  diagnostic: string
): BounceSubCategory {
  const msg = diagnostic.toLowerCase()
  if (code === 452 || code === 552 || msg.includes('mailbox full') || msg.includes('over quota'))
    return 'mailbox_full'
  if (msg.includes('does not exist') || msg.includes('no such user'))
    return msg.includes('domain') ? 'domain_not_found' : 'address_not_found'
  if (msg.includes('spam') || msg.includes('blocked'))
    return msg.includes('policy') ? 'policy_rejected' : 'content_blocked'
  return 'unknown'
}

Store subCategory on the BounceEvent model. Suppress on address_not_found and domain_not_found; retry with delay on mailbox_full; alert the deliverability team and pause the campaign on content_blocked or policy_rejected.