What happens when an email bounces or someone marks it as spam?

A suppression is a per-organization record that says "don't send to this address," and once one exists, every future send attempt to that address is blocked with a 422 RECIPIENT_SUPPRESSED response rather than actually going out. Suppressions get created for hard bounces, spam complaints, unsubscribes, or a manual entry. For every production send — Agent Inbox, API, templated, campaign — NevarMail writes a bounce, complaint or unsubscribe suppression the moment the provider reports the event, when your provider account's event webhook points at NevarMail. A provider pull sync every 6 hours also imports your provider's own bounce, spam-report and unsubscribe lists, which catches anything sent outside NevarMail.

What is a suppression, and why does it exist?

A suppressed address is dead weight at best (a hard bounce means the mailbox doesn't exist) and reputation damage at worst (a spam complaint tells the mailbox provider you're sending unwanted mail) — continuing to send to either one hurts your deliverability for every other recipient too. Suppressions are per-organization, and by default one blocks sends to that address across your whole account, not just the use case that triggered it.

A suppression can be scoped to a single use case instead of the whole account, but only opt-out reasons (unsubscribe, manual) respect that scoping — a hard bounce or spam complaint always blocks the address everywhere, because a bounced mailbox and a complaint are facts about the address, not about which use case happened to trigger them.

Does NevarMail add bounces and complaints automatically?

Yes. When the provider reports a spam complaint, or a bounce that proves the address does not exist, on any production send, NevarMail suppresses that recipient immediately and records it against the project the email was sent from. Test-mode sends never create suppressions.

Not every permanent bounce means a dead address, so NevarMail reads the receiving server's status code:

Your provider's own "invalid address" classification also counts as a dead address. Bounces that don't suppress are still recorded in Analytics. Your provider may keep its own bounce list regardless; the 6-hour sync imports it.

How do you add suppressions yourself?

POST /api/v1/suppressions

{
  "emails": ["bounced@example.com", "complained@example.com"],
  "scope": "account",
  "reason": "hard_bounce"
}

reason is one of hard_bounce, spam_complaint, unsubscribe, or manual (defaults to unsubscribe). scope is "account" (default) or "use_case", and use_case_id is required when scoping to a use case. The request accepts up to 1,000 addresses per call — larger lists go through the CSV import flow on the Suppressions settings page in the dashboard instead. The response reports how many were inserted versus already-duplicate versus invalid, and when reason is unsubscribe, NevarMail queues a best-effort sync to mirror the unsubscribe into your connected provider account as well.

How do you check if an address is suppressed before sending?

GET /api/v1/suppressions/check?email=someone@example.com

Returns whether the address is currently suppressed for mail from one project and, if so, why. Pass project_id for the project you would send from (it is optional when you pass use_case_id or your organization has one project). Suppressions are per project: an opt-out from one project never blocks another. Pass use_case_id to check a send to that use case's list — someone who left one list still gets your other lists, and a non-suppressable use case ignores opt-outs. A bounce blocks every project, and a bounce or complaint blocks regardless of use_case_id. This is the same check a send goes through automatically; using it ahead of time just lets you skip a send you already know will be rejected. See Why didn't my email send? for the full error-code reference if you'd rather just attempt the send and handle the rejection.

Can a suppressed address ever receive mail again?

Yes, but removal is a deliberate action, not automatic — it happens from the Suppressions settings page in the dashboard and requires a written reason of at least 10 characters (there's no bare "undo"). There is currently no /api/v1/* endpoint for removing a suppression; that's dashboard-only. Removing a suppression doesn't retroactively resend anything that was blocked while it was active — it only allows future sends to that address to go through.

Where do bounce and complaint events come from if not webhooks?

NevarMail's own outbound event webhooks (the ones you can register at /api/v1/webhook-endpoints) don't dispatch real bounce or complaint events yet — see the callout on Webhooks. Until they do, Analytics and the suppression list above are the two places to look: analytics for aggregate and per-message bounce/complaint history on sends NevarMail itself made, and the suppression list for which addresses are currently blocked and why.