KoltrixPer-customer suppression and bounce handling in a multi-tenant app
When many customers send through one platform, whose suppression list applies? Scope bounces and complaints per tenant and share only what is safe.
On this page(12 sections)
If you build a product where many customers send email through one platform, you quickly meet a question that single-company senders never face: when an address bounces for one customer, what happens for everyone else?
Suppress it for all, and a customer's typo or a one-off complaint blocks a message that another customer legitimately needs to send. Suppress it only for the customer involved, and the platform keeps retrying an address that is dead, which hurts reputation for everyone on shared infrastructure. The right answer depends on the type of event, and getting it wrong causes either lost mail or damaged deliverability.
This guide describes a practical model for multi-tenant suppression and bounce handling. For the basics of what to suppress, read suppression lists: what to suppress and for how long first.
The core idea: two layers
Use two lists with different owners and different rules.
- A tenant list. Each customer (tenant) has their own suppression list. It records what that customer should not send to, and why. It is private to the tenant.
- A platform list. The platform has a small, strict list of addresses that nobody should send to, because sending is demonstrably harmful or useless.
Every send checks both. The tenant list is about the relationship between that customer and that person. The platform list is about protecting shared reputation.
What belongs on the tenant list
Most events are about a relationship, so they stay inside the tenant.
| Event | Scope | Why |
|---|---|---|
| Unsubscribe | Tenant (and maybe the specific list or category) | The person opted out of this sender, not every sender on the platform |
| Spam complaint | Tenant | They complained about this sender's message |
| Manual suppression | Tenant | The customer decided to stop |
| Soft bounce repeated (mailbox full, temporary failures) | Tenant, with an expiry | Probably transient |
| Role address or unverified address the tenant chooses to skip | Tenant | A tenant policy |
A complaint to one tenant must not stop another tenant's transactional mail to the same person. The recipient may hate one newsletter and still need a password reset from a different product.
What belongs on the platform list
Reserve the shared list for cases that are about the address itself.
- Hard bounces for a non-existent mailbox (a 5.1.1 "user unknown"). The address does not work for anyone.
- Domains that do not exist or have no mail server.
- Known spam traps that you have identified. See spam traps explained.
- Addresses that asked for a global opt-out, where you offer one, or that sent a legal request to stop all mail.
- Abusive recipients that harvest or attack.
Be careful. A shared list is powerful, so every entry needs a reason, a timestamp and a way to be reviewed.
Distinguish permanent failures from blocks. "Mailbox does not exist" is about the address. "Your IP is blocked" or "message rejected as spam" is about the sender, and must not put the recipient on any list.
Classify the event correctly
The same SMTP response can mean different things, so parse it with care. See hard vs soft bounces and SMTP enhanced status codes.
- 5.1.1, 5.1.2: the mailbox or domain does not exist. Platform-level hard bounce.
- 5.2.x: mailbox state problems, such as full or disabled. Treat as soft or tenant-level.
- 5.7.x: policy or reputation refusal. About the sender, not the address. Do not suppress the recipient; investigate sending.
- 4.x.x: temporary. Retry with backoff; suppress only after repeated failures over days.
- A complaint through a feedback loop: a tenant-level event. See feedback loops and ARF.
Store the original response text and the classification, so a person can review a decision later. A bounce and complaint webhook pipeline shows how to ingest these events.
Tracking who sent what
To scope events correctly, every message needs identity.
- A tenant id on each outbound message.
- A message id that you can match to the bounce or complaint.
- A return path per tenant or per message, often using VERP-style addresses, so a bounce identifies the message without guessing. See From, Reply-To, envelope sender and Return-Path.
- The sending domain, especially when customers send from their own domains. See sending for customer domains.
If you cannot attribute a bounce to a tenant, do not guess. Record it as unattributed and handle it at the platform level.
Check at send time
At the moment of sending, check:
- Is the recipient on this tenant's suppression list for this category? Skip and record "suppressed".
- Is it on the platform list? Skip and record why.
- Is the tenant allowed to send to this address type, such as a role address, under their plan or policy?
Record skipped sends. A message that vanishes silently confuses customers, so give each skipped recipient a visible status and reason, such as "Not sent: the address previously hard bounced".
Do not leak private information across tenants. A tenant must not learn that an address is suppressed by another tenant. Show only "this address cannot receive mail" for platform-level hard bounces, and nothing about other customers' lists.
Customer controls
Give tenants tools to manage their own list.
- View and search suppressed addresses with reason and date.
- Remove an entry, with care. Removing a hard-bounce address from the tenant list should not override the platform list, and removing an unsubscribe should require evidence of fresh consent.
- Import their existing suppression list when they join, so past opt-outs are respected.
- Export it, for compliance and for leaving.
- Alerts when bounces or complaints rise.
Do not let a tenant clear complaint records so that they can mail unwilling people again.
Protect the platform from noisy tenants
One tenant with poor list hygiene can damage shared reputation.
- Set bounce and complaint thresholds per tenant, and warn, throttle or pause sending when they are exceeded. See the spam complaint rate threshold.
- Throttle by provider and by tenant to avoid bursts. See per-provider throttling.
- Consider separate IP pools or sending subdomains for risky or high-volume tenants. See shared vs dedicated IP.
- Review new tenants more closely at first, with lower limits that grow with a clean record.
Retries and idempotency
Bounce processing must be safe to repeat.
- Webhooks and feedback reports arrive more than once and out of order. Make suppression writes idempotent, keyed on the tenant and address and event id. See webhook consumers: retries and ordering.
- Do not retry permanent failures. See outbound retry and backoff.
- Keep an event history, not only the latest state. An email events data model describes one.
Expiry and review
- Hard bounces rarely expire, but check periodically. Mailboxes can return, and domains can come back.
- Soft bounces should expire after a period of success or time.
- Complaints and unsubscribes should not expire without fresh consent.
- Review the platform list regularly and keep an audit trail of who changed what.
Privacy and compliance
Suppression lists hold personal data. Store only what you need, protect it, and keep records to prove an opt-out was honoured. When a person asks for deletion, you may need to keep a minimal record (a hash of the address, for example) so you do not mail them again. Take legal advice on what is required in your markets.
Key takeaways
- Use two layers: a private tenant list for relationship events and a small platform list for harmful or useless addresses.
- Scope unsubscribes and complaints to the tenant; scope true non-existent-mailbox bounces to the platform.
- Do not suppress a recipient because of a sender-side block such as a 5.7 rejection.
- Attribute every message and bounce to a tenant, and record why each recipient was skipped.
- Give tenants visibility and control, but protect shared reputation with thresholds, throttling and review.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
