Handle bounces and protect your sending

Use the suppression list to find addresses Mail skips, and the reputation report to see whether bounce or complaint rates have paused sending. Mail maintains both records automatically. The statistics view summarizes sending and delivery outcomes.

Before you start: choose a product with Mail available. These records start with your first send; no activation is needed. The address examples use user@example.com; replace it with the recipient you are investigating.

Check whether an address is suppressed

Search the address. Call mail_suppression_list or GET /mail/suppressions on the Mail API. Use q for an address substring and reason to filter by suppression reason.
Read all matching entries. limit accepts 1–100 entries and defaults to 50. Pass the returned next_cursor as cursor to read the next page, until it is null. Each entry includes its address, reason, note, added time and, for a bounce or complaint, the event that caused it.

Check the result: an exact address match confirms suppression and gives its reason. A substring search can match other addresses, so compare the returned address and read all pages before treating it as absent. If the address is absent, investigate another delivery cause.

In Mail → Suppressions, the workspace shows Address, Reason, Note and Added. Use the tool or REST API for reason and substring filters; the table has no filter controls.

Why addresses land on the list

A suppression applies to a recipient address throughout one product. Mail checks every send against that product’s list.

Reason	How the address got there
`hard_bounce`	A message to it was permanently rejected
`complaint`	The recipient marked a message as spam
`unsubscribe`	The recipient used the unsubscribe link in a broadcast
`manual`	You added it yourself

Mail adds hard_bounce, complaint and unsubscribe entries automatically. You do not need to remove bounced addresses from your own lists to prevent sending. For broadcast unsubscribes, see send one message to a list of people.

Mail trims whitespace and lowercases addresses before storing and matching them. It applies no other normalization: user+tag@example.com and user@example.com remain separate addresses.

Add or remove an address yourself

Add a manual suppression. Call mail_suppression_add or POST /mail/suppressions with the address and an optional note of up to 1000 characters. Use this when someone asks you to stop or you know a mailbox is unavailable. The reason is manual. In Mail → Suppressions, Add suppression opens Address and Note (optional) fields; the note field itself has no length control.

Check the result: read the address back from the list. Repeating an add preserves the original entry and reason; it creates no duplicate.
Remove a suppression when appropriate. Call mail_suppression_remove or DELETE /mail/suppressions/:address. In the workspace, select Remove on its row and confirm Remove <address>?. Check the result: removed: true means an entry was removed; false means none existed. Removing an absent address succeeds without an error.

Suppressions never expire. Remove one only after confirming the address can receive mail again. Sending to a mailbox that still hard-bounces will add it back to the list.

What happens when you send to a suppressed address

Mail accepts the message and applies suppression to each recipient across to, cc and bcc:

Mail removes suppressed addresses before delivery.
Each skipped address produces an email.suppressed event in message history and webhooks.
When recipients remain, Mail queues and sends to them.
When no recipients remain, the message becomes suppressed and is never handed over.

Mail checks suppression at acceptance and again just before sending. An address added during a scheduled wait is therefore skipped too. If that leaves no recipients, the scheduled message becomes suppressed.

Bounces and complaints

Mail records the receiving server’s outcome in the message’s event history. Hard bounces and complaints also change status and suppress the address:

Outcome	What it is	Effect
Hard bounce	A permanent rejection — the mailbox does not exist, the domain does not accept mail	Status becomes `bounced`; the recipient is added to the suppression list
Soft bounce	Temporary — a full mailbox, a server that was busy	Recorded as an event with bounce kind `soft`, or `undetermined` when the receiving server was not specific. The status does not change and no address is suppressed
Complaint	The recipient pressing “this is spam”	Status becomes `complained`; the address is suppressed

Subscribe to delivery webhooks for these events, or read the message to inspect its history.

Read your reputation

Read the report. Call mail_reputation_get or GET /mail/reputation. There is no workspace screen for this report. It covers a rolling window ending now. Read window_days for its configured length; the documented default is 7 days:

Field	Meaning
`volume`	Recipients of sent emails whose send time falls within the window; a message to four recipients counts as four
`hard_bounces`, `complaints`	Hard-bounce and complaint events occurring within the window; counts events, not unique addresses
`hard_bounce_rate`, `complaint_rate`	Event counts divided by `volume`, as ratios between 0 and 1; zero when `volume` is zero
`thresholds`	The limits the two rates are measured against, and the minimum volume
`gated`	Whether sending is currently throttled
`tripped_metric`	`hard_bounce`, `complaint`, or `null` when nothing tripped
`window_days`	The length of the window the numbers cover

Check whether sending is paused. gated: false with tripped_metric: null means reputation is not throttling sending. If gated is true, tripped_metric identifies the affected rate.

Read the configured limits in thresholds. The documented defaults are a 4% hard-bounce rate, 0.08% complaint rate and 1000-recipient minimum volume. A gate requires volume at least thresholds.min_volume and a rate strictly greater than its threshold. A rate equal to the threshold does not trip it. If both rates trip, tripped_metric is hard_bounce.

What happens while you are gated

A reputation gate pauses sending for the whole product. New requests return reputation_throttled with the rate, threshold and window. Mail also checks queued and scheduled messages when they come due; gated messages become blocked.

Sending resumes automatically when the report no longer meets the gate conditions. No manual reset is needed. Stop sending to people who did not ask to hear from you and to addresses that bounce; automatic suppressions prevent further sends to permanently rejected addresses.

The report may be cached for up to 60 seconds, so recent sends or events may not appear immediately.

Read your statistics

Choose a period. Call mail_stats_get or GET /mail/stats with period: "7d", "30d" or "90d". The default is "30d". Statistics cover the whole product.
Compare totals and outcomes. The workspace’s Mail dashboard uses the same periods. It shows four totals and deltas, Email volume by day and Deliverability percentages. Recent activity and Domains use separate data. The tool returns the full statistics below.

Group	What it holds
Totals	`sent`, `delivered`, `bounced` and `complained` for the period. `sent` counts recipients of messages that were handed over, not messages, so a single message to four people counts as four.
Deltas	The change in each total against the immediately preceding period of the same length, as a percentage. A delta is `null` when the previous period was zero, because there is no meaningful change from nothing.
Volume	One bucket per UTC day across the period, each with its `sent`, `delivered` and `bounced` counts. Days with no activity are present with zeroes, so the series is always the full length of the period.
Deliverability	`delivered`, `bounced` and `complained` as percentages of `sent`, rounded to one decimal place, and zero when nothing was sent.

Check the result: the response identifies the selected period and returns totals, deltas, daily volume and deliverability percentages.

Delivery, bounce and complaint counts include events received within the window. A message sent near its end may get an outcome later, so recent delivery percentages can initially look low and settle as events arrive.

Next steps

Receive delivery events: Receive bounce and complaint notifications.
Send a message: Interpret suppressed and blocked messages.
Set up a sending domain: Publish sender DNS records.
How system email works: Understand the message lifecycle.

Was this page helpful?