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 Agent Inbox sends NevarMail writes them the moment the provider reports the event. For every other send path — API sends, templated sends, campaigns — they arrive with the provider pull sync, which runs every 6 hours and imports your provider's bounce, spam-report and unsubscribe lists. If you cannot wait for the next sync, push the address yourself with the endpoint below.

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, on two timelines. Immediately for Agent Inbox sends in production mode. When SendGrid reports a hard bounce or spam complaint for a message sent from an inbox, NevarMail writes a suppression for that recipient automatically, org-wide. A soft/transient bounce (SendGrid's blocked classification) does not — a temporarily-unreachable mailbox isn't a dead address.

For every other send path — the transactional API, templated sends, and campaigns — NevarMail does not ingest delivery events in real time. Instead a background sync runs every 6 hours and pulls your provider's bounce and spam-report lists into your suppressions (transient blocked entries are skipped, for the same reason as above). So an address that hard-bounced on an API send is blocked within six hours, not instantly. If a send is going out before then and you already know an address is bad, push it yourself with the endpoint below.

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 and, if so, why. Pass use_case_id to check whether a use-case-scoped opt-out applies — a bounce or complaint still blocks regardless of use_case_id, since those aren't scoped opt-outs. 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.