Bounces and suppression

What happens when delivery fails permanently, and how the relay protects pool reputation.

Bounce DSN

When a message exceeds retry attempts or the recipient returns a 5xx, the relay marks it bounced and sends an RFC 3464 Delivery Status Notification (DSN) to the original sender.

The DSN is a multipart MIME message with three parts:

1. text/plain: human-readable explanation of the failure.
2. message/delivery-status: machine-readable fields including Original-Recipient, Final-Recipient, Action (failed), Status (e.g. 5.1.1), and Diagnostic-Code with the recipient MX’s response.
3. message/rfc822-headers: the headers of the original message, including Message-ID so you can correlate the bounce to your send.

Parse the message/delivery-status part programmatically. The Diagnostic-Code field carries the verbatim 5xx response from the recipient, which is the most useful field for debugging.

Where DSNs go

DSNs are addressed to the original envelope sender. For relay-submitted mail, that’s a VERP-encoded address at atmos.email, which the relay receives at its inbound listener and forwards to your domain’s forward-to mailbox if one is set. If forward-to is empty, the DSN is logged but not delivered. See Reply forwarding to set up forward-to.

The suppression list

The relay maintains a per-DID suppression list. An unsubscribe click, an operator action, an address-level delivery failure, or an authenticated feedback report with a matched recipient can add a recipient to it. Suppression checks apply to bulk, broadcast, untagged, and unrecognized message categories. When every recipient is suppressed, SMTP returns 550 5.7.1 All recipients have unsubscribed; HTTP and XRPC sends report ALL_RECIPIENTS_SUPPRESSED. For a mixed batch, the relay filters suppressed recipients and proceeds with the rest.

• Suppressions are per-DID, not relay-wide. A recipient who unsubscribed from one member is not blocked for others.
• Suppressions persist for the life of your member record. There is no expiration.
• The recognized user-initiated categories login-link, password-reset, mfa-otp, and verification bypass suppressions caused only by an unsubscribe and omit List-Unsubscribe. The generic value transactional is not a recognized exemption.

Suppressions from bounces, complaints, operator actions, and unknown sources still apply to these categories. The relay records the sender’s category claim, but that claim does not prove the message was user-initiated. Members must keep their recipient lists accurate and honor consent independently of this exemption.

Hard bounces

The relay records per-DID suppression rows for permanent address failures, such as 550 5.1.1 User unknown, on direct delivery and inbound delivery-status reports. It does not suppress on every 5xx: reputation or policy blocks, full mailboxes, temporary failures, and unparseable bounce reports do not qualify by themselves. A specific enhanced status code takes precedence over suggestive response text. Stronger suppression evidence can update an existing row.

These rows are not a relay-wide recipient block. Remove invalid addresses from your own sending list, including lists used for transactional messages.

The safety net is the per-domain auto-pause below. It catches sending domains that drift into bad reputation before the shared pool suffers.

Per-domain auto-pause

The relay evaluates each sending domain every 15 minutes against a 24-hour rolling window. A domain is automatically paused when either limit is reached:

• Bounce rate: 5% with at least 10 messages and 3 hard bounces in the window.
• Spam complaint rate: at least 0.08% with at least 10 messages in the window.

Auto-pause is scoped to the offending domain, not the whole account. If you operate multiple sending domains, the others keep sending.

Other account-level safety checks may also block sending. Check your account for the reason.

A high bounce rate signals one of:

• You’re sending to an outdated list with many dead addresses.
• You’re being mistaken for a spam source by recipient mail servers.
• Your DNS authentication is broken (see DNS records).

To unpause, sign into /account and visit the domain detail page. Address the underlying cause first; unpausing without fixing the bounce source will trigger another pause on the next evaluation cycle.

Complaints (ARF feedback)

Some providers send Abuse Reporting Format (ARF) reports through their registered feedback programs. The relay requires valid operator DKIM covering the original message ID and member DID before attributing a report. Not every provider or complaint produces a report.

Complaint rate is one of the two signals the per-domain auto-pause evaluator watches (0.08% threshold per the section above). An authenticated complaint report can add a recipient to the suppression list when the relay can match it to a recipient. Reports without a matching recipient cannot create a recipient suppression.

Real-time notifications

The aggregate counts above power the dashboard and the /member/deliverability polling API. If you’d rather get a push notification per bounce or complaint, subscribe to message.bounced and message.complained via webhooks.

Back to docs