Bounce handling
A bounce is the receiving side telling us a message cannot be delivered. What happens next depends entirely on whether it said “never” or “not now”.
Hard and soft
A hard bounce is a permanent failure. The SMTP status begins with 5, or
a failure report arrives with a 5.x.x status and an action of failed. The
address does not exist, the domain refuses you, or the message was rejected
outright.
The platform:
- marks the message
bounced; - adds the recipient to your suppression list, immediately and automatically;
- counts it toward the 24 hour bounce rate the reputation engine watches;
- fires
delivery.dsn-perm-fail.
A soft bounce is a temporary failure. A 4.x.x status, a greylist, a full
mailbox, a busy server. It is not a bounce in any way that matters here: it
does not suppress, it does not count toward your bounce rate, and the mail
server keeps retrying for days.
A delayed-delivery notice is also not a bounce. Only failed plus a 5.x.x
status qualifies.
Two routes in
Bounces reach the platform two ways, and you will see the effect of both.
The mail server’s own delivery events, in real time, which is how most
bounces arrive and why a delivery.dsn-perm-fail webhook usually lands within
seconds.
A collector that reads bounce reports from the return path, for reports that arrive as ordinary email rather than as a delivery event. It parses the report, ties it to the original message, and records the bounce. Reports our own server generated are recognised and not double-counted.
If you have set a custom Return-Path, that is where those reports go, and the collector reads them from there.
Seeing them
curl -s "https://api.lockally.com/v1/messages?status=bounced" \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
GET /v1/messages/{id} carries a bounce_reason with the SMTP text, and
GET /v1/messages/{id}/events gives the per-recipient timeline. Aggregate
counts by outcome come from GET /v1/messages/stats.
What to do about them
Remove the address at source. Suppression stops the message leaving, but it does not stop your application from asking, and it does not improve your bounce rate: the rate is computed from what actually went out and failed. Fixing it in your own database is the only thing that moves the number.
Do not retry a hard bounce. There is nothing to retry. Re-submitting across a cleaned-looking list is the most common way workspaces trip the reputation engine.
Investigate a sudden cluster. A spike at one provider is usually a reputation or authentication problem at that provider, not a list problem. Check authentication before blaming the addresses.
The one thing to know about hard bounces here
The suppression is per workspace, across every stream. A hard bounce from a marketing send blocks that address for your transactional mail too, password resets and receipts included.
That is the right default, because an address that does not exist does not exist for receipts either. It is also a sharp edge if a bad import poisons addresses that were fine. Suppression management covers how to see the list and remove an entry.