Troubleshooting: email bounces and spam complaints

bounced is the email channel’s terminal failure status — a receiving mail server returned the message instead of accepting it. Because email accepts a message and then bounces it later, the bounce arrives on the same asynchronous webhook path as delivery. This page decodes the DSN codes and SMTP replies the provider reports, maps each failure family to the fix, and shows how to read the sender-reputation summary before you escalate. If the message was never accepted at all (failed, rejected on send), work the channel-agnostic message failure page first — this page covers only recipient-side rejects after the provider accepted the send.

Where you see a bounce

Three surfaces carry the same outcome:

Delivery Log — open the row. A recipient-side bounce resolves to the terminal status bounced — the email-only terminal status that lives in the platform’s terminal-failure set alongside failed, undelivered, and expired (see the message status lifecycle reference). The Provider Reference and the failure detail the provider returned travel with the row.
Webhook — email delivery outcomes arrive on the channel-agnostic message events, not email-specific ones. A hard bounce, a soft bounce, and a spam complaint all fire message.failed with channel: "email" and the originating message_id (see the email channel guide). Branch on the payload’s failure detail, not the event type.
Deliverability dashboard / API — the tenant-level summary endpoint GET /api/v1/email/suppressions/reputation returns the aggregate sent / delivered / bounced / complaint counts and rates, the health tier and score, and the current suppression-list size over a lookback window (see the email endpoints reference). Compare a single bounce against this baseline before treating it as a trend.

Hard vs soft vs complaint vs spam-trap

The provider reports a DSN (Delivery Status Notification) code and the SMTP reply from the rejecting server. Classify it before you act:

Family	What the code says	What it means
Hard bounce	`5.1.1` (invalid mailbox), any `5.x.x`	The address does not exist or the domain/ recipient server rejects permanently. Retrying the same address will fail again — remove it.
Soft bounce	`4.x.x` (mailbox full, temporarily deferred, greylisted)	The recipient server throttled or deferred this attempt. Within the provider’s retry window the send can still succeed; a persistent `4.x.x` across retries degrades into a hard failure.
Spam complaint	Recipient clicked “report spam”	The recipient told their provider your message is unwanted. The complaint counts against your sender reputation even when the message technically delivered.
Spam trap / blocklist	The deliverability-surface complaint bucket the reputation endpoint groups	An address that exists only to catch senders who bought lists or never re-validate. A few trap hits can pull the whole sender’s health tier down.

Read the provider’s raw reply on the Delivery Log row — 5.1.1 (user unknown) and 5.2.2 (mailbox full) look identical from the bounced status alone, and the fix differs.

Cause → fix

Signal	Fix
Hard bounce (`5.x.x`)	Remove the address and let the suppression list hold it. A complaint-driven suppression entry stops future sends to that address automatically (see opt-out suppression); purging invalid addresses before they re-bounce is cheaper than rebuilding reputation after.
Soft bounce (`4.x.x`)	Retry within the provider’s retry window, and watch the aggregate soft-bounce rate on the reputation endpoint. A high soft-bounce share means a destination ISP is throttling you — treat it as early signal, not noise.
Spam complaint	Review signup/list hygiene: confirm consent was collected, the opt-out flow is one click, and the sender identity is clear. Each complaint suppresses the recipient and drags the complaint-rate bucket the reputation endpoint reports.
Spam trap	Audit the import source. Trap contamination means addresses came from a purchased or scraped list, or an ancient un-validated import — remove list-purchase sources and re-validate before the next send.
Delivered to spam folder	Check SPF/DKIM/DMARC alignment on the sending domain and run the deliverability-score lint (spam-trigger keywords, shortened links) before re-sending. “Delivered” in the log with no engagement is a placement problem, not an acceptance problem.
Warmup held at a daily cap	Working as designed — the daily cap is a ramp, not a fault. Check today’s recommended cap and remaining headroom with `GET /api/v1/email/warmup-status`; the day-by-day ramp is described in the warm-up FAQ entry.

Lifetime reputation is the score that decides which of these levers exists at all. Keep the complaint rate near zero and prune hard bounces after the first return — the reputation endpoint’s health tier and score reflect both.

Reading the deliverability surface

GET /api/v1/email/suppressions/reputation summarises a lookback window into the numbers to report and trend:

sent / delivered / bounced / complaint counts and rates — the raw numerator and denominator for each outcome family so a spike in one bucket does not hide in a blended rate.
health tier and score — an ordinal-priority view of how the provider-side reputation stack currently scores the sender.
suppression-list size — how many addresses the suppression list is actively holding out of future sends right now.
shared-IP disclosure — whether the sender shares sending IP with other tenants, which affects how much of your own bounce/complaint budget a given number can consume before the pool-averaged health is diluted.

Requires an owner or admin role. Full request/response shape is in the email endpoints reference.

When to escalate

Escalate when the bounce family is genuinely ambiguous or the numbers are off in a direction you cannot correct from your own list source:

All destinations return the same family at the same time (points at the sending side, not one list).
The reputation endpoint shows a complaint rate hard-correlated with a specific campaign or template.
SPF/DKIM/DMARC align and content passes the deliverability-score lint, yet bulk traffic still lands in spam.

Include these so support traces the row without a back-and-forth:

Your tenant ID (Settings → Organization in the dashboard; also returned as organizationId by GET /api/v1/me).
One message ID of a bouncing row (msg_…).
The bounce code / SMTP reply as the provider returned it (read from the Delivery Log row’s failure detail).
Your complaint rate over the lookback window, from the reputation endpoint.

​Troubleshooting: email bounces and spam complaints

​Where you see a bounce

​Hard vs soft vs complaint vs spam-trap

​Cause → fix

​Reading the deliverability surface

​When to escalate

​See also

Troubleshooting: email bounces and spam complaints

Where you see a bounce

Hard vs soft vs complaint vs spam-trap

Cause → fix

Reading the deliverability surface

When to escalate

See also