I'm building a product that needs bounce handling and suppression lists

To handle bounces and suppression lists well, you’ll want to build a small email-deliverability subsystem around your sending pipeline.

Core concepts

1) Bounce handling

A bounce is when an email can’t be delivered.

• Hard bounce: permanent failure
  Examples: invalid address, domain doesn’t exist, recipient blocked permanently.

  • Action: usually suppress the recipient immediately.

• Soft bounce: temporary failure
  Examples: mailbox full, temporary server issue, message too large.

  • Action: retry for a limited time / number of attempts, then suppress if persistent.

2) Suppression list

A suppression list is a set of recipients you must not email.

Common reasons to suppress:

• Hard bounce
• Unsubscribe
• Complaint/spam report
• Manual opt-out
• Invalid address / syntax failure
• Abuse/fraud risk
• Legal/compliance reasons

Recommended architecture

A. Sending flow

Before sending each message:

1. Normalize recipient email
2. Check suppression list
3. Check campaign-level eligibility / consent
4. Send if allowed
5. Record message metadata for later bounce correlation

B. Bounce ingestion flow

When your ESP/mail provider notifies you via webhook, parser, or IMAP:

1. Parse the event
2. Match bounce to original recipient/message
3. Classify bounce type:
   • hard
   • soft
   • complaint
   • unsubscribe
   • block
4. Update suppression or retry state
5. Log for analytics and support

Data model suggestion

suppression_list

• id
• tenant_id / account_id
• email
• reason
  e.g. hard_bounce, complaint, unsubscribe, manual, invalid
• source e.g. ses, sendgrid, admin, import
• created_at
• expires_at optional
• metadata JSON optional

message_delivery

• id
• message_id
• tenant_id
• email
• provider_message_id
• status
• sent_at
• bounced_at
• bounce_type
• bounce_code
• raw_event JSON

bounce_event

• id
• provider
• provider_event_id
• message_id
• email
• bounce_type
• diagnostic_code
• status_code
• occurred_at
• processed_at
• raw_payload

Bounce classification rules

A useful default mapping:

• Hard bounce

  • 5xx SMTP permanent failure
  • user unknown
  • invalid recipient
  • domain not found
  • address rejected

• Soft bounce

  • 4xx SMTP temporary failure
  • mailbox full
  • try again later
  • temporary lookup failure

• Complaint

  • feedback loop / spam complaint
  • suppress immediately

• Unsubscribe

  • user opt-out
  • suppress immediately for marketing, possibly still allow transactional if policy permits

Operational recommendations

Immediate suppression

Suppress immediately on:

• hard bounce
• complaint
• unsubscribe
• invalid address
• role addresses if you choose to block them (admin@, postmaster@, etc.)

Retry policy for soft bounces

Example:

• retry after 15 min
• then 1 hour
• then 6 hours
• then 24 hours
• stop after 3–5 attempts or 72 hours

Deduplication

Use:

• provider_event_id
• message_id
• (tenant_id, email, event_type, occurred_at window)

to avoid double-processing webhook retries.

Multi-tenant support

If your product serves multiple customers:

• isolate suppression lists by tenant
• optionally maintain a global suppression list for compliance-related entries
• be careful not to leak one customer’s suppression data to another

Important edge cases

• Plus-addressing: normalize cautiously (user+tag@example.com may be distinct for some users, but you generally suppress at the exact address used)
• Case sensitivity: treat local part case-insensitively in practice for most systems
• Alias forwarding: bounce may originate from a forwarding layer, not the original address
• Shared suppression: a single hard bounce should not suppress a different address at the same domain unless your policy says so
• Transactional vs marketing: unsubscribe should usually suppress only marketing unless the user opted out globally

Privacy/compliance

• store only necessary data
• log raw bounce payloads carefully because they may contain personal data
• support deletion requests where applicable
• keep an audit trail for suppression changes

If you’re using a provider

Most email providers already emit bounce/complaint/unsubscribe events:

• AWS SES
• SendGrid
• Mailgun
• Postmark
• SparkPost

Typically you’ll:

• configure event webhooks
• verify signatures
• map provider event types into your internal schema
• feed them into suppression logic

Minimal implementation checklist

• suppression table
• send-time suppression check
• webhook/event ingestion
• bounce classification
• retry logic for soft bounces
• unsubscribe/complaint handling
• audit logging
• idempotent processing

If you want, I can also give you:

1. a database schema,
2. a bounce classification algorithm, or
3. a reference implementation in your preferred language.