# Handling a spam complaint, end to end

A complaint arrives as a notification from a mail provider rather than as a message from the person. Connect identifies the recipient, records a suppression carrying *complaint* as its origin, and every later outreach to that address is refused by the one compliance check. The second half is the part that matters longer: a complaint is evidence about how a workspace sends, not only about who it sent to.

- **Status:** Available
- **Audience:** both
- **Channels:** email
- **In the app:** #/inbox, #/relationships, #/needs-you
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/complaint-handling/

## The flow, stage by stage

1. Trigger — a recipient marks a message as spam in their own mail client.
2. External event — their provider notifies the sending side; this arrives as a signed notification, not as an email.
3. Authentication and workspace resolution — the notification is matched to the mailbox that sent the message, and the mailbox is what names the workspace.
4. Ingest — the notification is normalised: which address complained, about which message.
5. Canonical record — a suppression is written for that recipient with `complaint` as its origin and the time it happened.
6. Classification and reasoning — a complaint is not a bounce and is not an unsubscribe; treating them alike loses the distinction that makes each one actionable.
7. Knowledge, memory and rules — the person's record gains the entry, so anyone opening the relationship sees it before writing.
8. Autonomy and approval — no bearing. The suppression applies to an autonomous workspace exactly as to a supervised one.
9. Action through a provider — none outbound. Nothing is sent in response to a complaint, and nothing apologises for one.
10. Result — every subsequent outreach to that address is refused, with the origin named in the refusal.
11. Relationship, timeline and memory — the complaint is part of the person's history, which is what stops a colleague re-adding them to a list next quarter.
12. Audit, usage and Needs You — the entry and every refusal it causes are recorded as decisions.

> **Note** The webhook that receives these notifications has to find its mailbox before any workspace is known — it is the one mail path that cannot start from a session. That is why it resolves the mailbox first and enters the workspace from there.

## What a complaint is, and what it is not

| Signal | What it says | What it changes |
|---|---|---|
| Complaint | The recipient considers the message unwanted | A suppression with `complaint` as its origin, and a question about the sending practice |
| Unsubscribe | The recipient asked to stop, through the route offered to them | A suppression with `unsubscribe` as its origin; no reputational signal |
| Bounce | The address did not accept the message | Depends on the classification — see [Handling a bounce, end to end](/docs/workflows/bounce-handling/) |

Keeping them apart is what makes any of them useful. A workspace with many unsubscribes has an audience problem; a workspace with many complaints has a relevance or a consent problem, and those need different corrections. Collapsing all three into one list produces a number that cannot be acted on.

## The sender-side change

The suppression protects one person. What protects the mailbox is what happens next, because complaints are read by receiving providers as a statement about the sender rather than about a single message. A pattern of them affects whether later mail — including ordinary replies to customers — reaches an inbox at all.

- **Look at what was sent, not only at who complained.** One complaint is noise; several against one campaign is a message about the campaign.
- **Check consent evidence before the next outreach run.** Prospecting keeps evidence for contactability, and a complaint is a reason to re-read it rather than to send harder.
- **Reduce volume before improving wording.** Sending less to a better-qualified list moves the number that matters; rewriting a subject line rarely does.
- **Never respond to a complaint with a message.** The recipient has already said what they wanted, and an apology sent to a suppressed address is the exact behaviour that generated the complaint.

> **Careful** Do not clear a complaint suppression to finish a sequence. The entry records that a person reported the mail as unwanted; removing it to continue sending is the decision the origin field exists to make visible.

## Failure modes

**The complaint cannot be matched to a person** — The address is suppressed regardless. Compliance works on the address; the relationship link is a convenience, not a precondition.
**The complaint arrives after the sequence finished** — The suppression still stands and still refuses future outreach. Nothing is retroactive, and nothing already delivered can be recalled.
**A colleague re-imports the address** — The suppression is read at the send gate rather than at import, so the entry still refuses. The import is not the protection.
**Complaints keep arriving from one campaign** — Stop the campaign. Each further message is another recipient's chance to report the sender rather than the message.

## What a person should actually do

1. Open the person's record and read the entry with its origin.
   - Result: You know whether this was a complaint, an unsubscribe or a bounce, which decides everything that follows.
2. Leave the suppression alone.
   - Result: The recipient stops hearing from the workspace, which is what they asked for and is also what protects the mailbox.
3. Look at the other recipients of the same run.
   - Result: You find out whether this is one person's preference or a batch that should not have been sent.
4. Record what you learned as a standing instruction if it should change future outreach.
   - Result: The lesson survives the campaign, rather than living in one person's memory of a bad week.

## Questions

### Does Connect email the person to apologise for a complaint?

No. Nothing outbound is sent in response to a complaint. The recipient has already said the mail was unwanted, and a further message to a suppressed address would be the same mistake repeated.

### Is a complaint the same as an unsubscribe?

No, and the origin is stored so the difference survives. An unsubscribe used the route offered; a complaint went to the recipient's own provider, which is a signal about the sender and not only about the message.

### Can the suppression be removed if the person says it was a mistake?

It can be cleared like any suppression, and the origin makes plain what is being cleared. Removing a complaint entry to continue a sequence is a decision worth making deliberately rather than quietly.

## Related

- [Spam complaints](https://connectbyjbrh.com/docs/email/complaints/)
- [Deliverability](https://connectbyjbrh.com/docs/email/deliverability/)
- [Applying a suppression, end to end](https://connectbyjbrh.com/docs/workflows/suppression-application/)
- [Handling a bounce, end to end](https://connectbyjbrh.com/docs/workflows/bounce-handling/)
- [The compliance check before outreach](https://connectbyjbrh.com/docs/prospects/compliance-check/)

## What this page is based on

- CHANNELS.md §1 — compliance, and the webhook that resolves its mailbox first
- GENERAL.md §5 — the audit trail records refusals
- `backend/app/comms.py`, `prospect_compliance.py`
- Connect capability registry (docs-source/facts.py) — `suppression_dnc`