In the last post I was on the receiving side of a spam decision and could see almost nothing. Four authentication checks passed, the message went to Spam anyway, and the reason stayed with Gmail. On the sending side the providers do tell you a few things, in a format a program can read. Whether anything in your system changes because of it is up to you.
I worked on that when I built an SMTP platform that sent millions of emails a month. Applications, CRMs and marketing tools posted messages to an API written in Go, and the API handed them to a pool of MTAs, the mail servers that open the SMTP connection to Gmail, Outlook or Yahoo. When a provider said no, the answer came back as an email. Either a bounce, a notice that a message couldn’t be delivered, or a complaint, the report some providers send when one of their users presses “report spam”.
None of the pieces was hard to build. What took thought was where the check sits. A suppression list someone opens after a bad week tells you what went wrong. The same list read by the API on every request keeps the platform from doing it again, and that placement is the part of the design I’d still defend.
Where the notices come from #
Most refusals happen during delivery, “about 95% of all returns” according to the 2015 Sender Best Common Practices from M3AAWG, the group where mailbox providers and senders write down shared practice. The rest come later from servers that accepted the message first. SMTP is a conversation, and after the MTA names the recipient the receiving server answers with a code. A 550 means the message was refused. The MTA knows right away, the API that took the message from a customer doesn’t, and the MTA tells anyone by writing a failure notice to the envelope sender. That’s the address in MAIL FROM at the start of the conversation, separate from the From: a reader sees. RFC 5321 says its primary purpose “is to designate the address to which messages indicating non-delivery or other mail system failures are to be sent”, and the final server copies it into the Return-Path header.
Complaints come from a person. When someone at Yahoo or Outlook.com presses the spam button, the provider can send a report through a feedback loop, a program the sender signs up for with each provider. Yahoo keys its loop on the DKIM signing domain and Microsoft on the sending IPs, so the platform had to be the signer or own the IPs. Gmail doesn’t send these per message.
So every message left with an envelope sender on a domain whose MX record pointed at Amazon SES. Bounces came back there by protocol, and the feedback loops were registered to send there too. That domain is also the one SPF checks, so its SPF record still has to list the MTAs that send.
Reading a bounce #
A standard bounce is a multipart/report email (RFC 6522) with three parts. Text for a human, a message/delivery-status part from RFC 3464 that a program can read, and, when the server includes it, the original message or its headers.
Content-Type: message/delivery-status
Reporting-MTA: dns; mx.example.net
Final-Recipient: rfc822; someone@example.net
Action: failed
Status: 5.1.1
Diagnostic-Code: smtp; 550 5.1.1 The email account that you tried to reach does not exist
Action: failed means the MTA gave up, delayed means it’s still trying. Status is an enhanced status code from RFC 3463, where the first number is the class. 2 is success, 4 a temporary failure, 5 permanent. Diagnostic-Code is the server’s own words, and the M3AAWG practices warn that the numeric codes “do not clearly state whether or not the address should be removed”.
The classifier has to decide something narrower than hard or soft, whether the notice describes the address or the sender.
| Status | Meaning | Describes |
|---|---|---|
5.1.1 | Bad destination mailbox address | The address |
4.2.2, 5.2.2 | Mailbox full | The address, for now |
5.7.1 | Delivery not authorized, message refused | The sender or the message |
Gmail sends a missing mailbox as a clean 5.1.1, “550 5.1.1 The email account that you tried to reach does not exist”. Microsoft answers with “550 5.4.1 Recipient address rejected: Access denied” and Yahoo with “554 delivery error: dd This user doesn’t have a yahoo.com account”, with no enhanced code at all. A classifier that reads only Status sends both to review, and matching the text provider by provider comes after that. Every message sent to a real 5.1.1 after the first notice is a bounce the sender chose to produce. Gmail’s sender guidelines say “Automatically unsubscribe recipients who have multiple bounced messages.”
A 5.7.1 is also permanent, and suppressing on it is the mistake I’d most want someone building this to avoid. RFC 3463 says the sender “is not authorized to send to the destination”, which “can be the result of per-host or per-recipient filtering”. The filter may be looking at the IP, the domain or the content, and none of that says whether the address exists. Suppress on it and the sender problem stays, plus a list of good recipients nobody writes to again.
Temporary failures get retries from the MTA first. When it gives up, the notice says Action: failed and can still carry the 4 status of the last attempt. A 4.2.1 or 4.2.2 is a disabled or full mailbox and counts toward the address. A 4.7.x means the server deferred the sender, which is how a provider slows down an IP it doesn’t trust yet. An MTA that gives up after days of 4.7.0 writes a failed notice for every recipient at that provider, and a counter that takes those suppresses a provider’s worth of good addresses. Those go to review. Some servers send a full mailbox as 5.2.2, and at Gmail the 5.2.2 means “out of storage space and inactive”. It’s still a full mailbox, so it goes into the count.
The platform counted every soft bounce per address and suppressed at a limit. Today I’d count only the mailbox codes, for the reason above. M3AAWG suggests removing an address that “bounces consecutively at least two times over two weeks or more”. Mailchimp allows 7 soft bounces for an address with no activity and 15 for one with activity, and a delivery in between resets the count. The sketch below has no reset, and I’d add one first.
The decision in Go, written for this post and not taken from the platform. It takes the Action and Status of one recipient in the notice.
// Package dsn decides what a delivery status notification asks a sender to do.
package dsn
import (
"errors"
"fmt"
"strings"
)
// Verdict is what the feedback pipeline does with one recipient of a notice.
type Verdict int
const (
// Review keeps the address off the suppression list until a person reads the notice.
Review Verdict = iota
// Ignore means the notice reports no final failure.
Ignore
// CountTransient adds one transient failure to the address's count.
CountTransient
// Suppress stops future sends to the address for the client that sent the message.
Suppress
)
// String returns the name of v, or Verdict(n) for a value outside the set.
func (v Verdict) String() string {
names := [...]string{"Review", "Ignore", "CountTransient", "Suppress"}
if v >= 0 && int(v) < len(names) {
return names[v]
}
return fmt.Sprintf("Verdict(%d)", int(v))
}
// ErrStatus is wrapped by the error Classify returns when the Status field
// is not an enhanced status code as defined in RFC 3463.
var ErrStatus = errors.New("not an enhanced status code")
type status struct{ class, subject, detail int }
// Classify returns the Verdict for one per-recipient group of a
// message/delivery-status part (RFC 3464), given its Action and Status
// field values. Surrounding spaces are ignored, the action is matched
// without regard to case, and anything from the first parenthesis on is
// dropped from the status, where RFC 3464 allows a comment.
//
// Only a failed recipient can be counted or suppressed. A mailbox that
// does not exist (5.1.1) or whose domain publishes a null MX (5.1.10) is
// Suppress. A disabled or full mailbox (4.2.1, 4.2.2, and 5.2.2 from
// servers that send a full mailbox as permanent) is CountTransient. Other
// transient codes describe the route or the sender, not the address, and
// are Review with every other failed status. A delayed, delivered, relayed
// or expanded recipient with a valid status is Ignore, and any other action
// is Review. A malformed status returns Review and an error wrapping
// ErrStatus.
func Classify(action, statusField string) (Verdict, error) {
s, ok := parseStatus(statusField)
if !ok {
return Review, fmt.Errorf("dsn: status %q: %w", statusField, ErrStatus)
}
switch strings.ToLower(strings.TrimSpace(action)) {
case "delayed", "delivered", "relayed", "expanded":
return Ignore, nil
case "failed":
switch {
case s == status{5, 1, 1}, s == status{5, 1, 10}:
return Suppress, nil
case s == status{4, 2, 1}, s == status{4, 2, 2}, s == status{5, 2, 2}:
return CountTransient, nil
}
}
return Review, nil
}
func parseStatus(field string) (status, bool) {
code, _, _ := strings.Cut(field, "(")
parts := strings.Split(strings.TrimSpace(code), ".")
if len(parts) != 3 {
return status{}, false
}
var n [3]int
for i, p := range parts {
if p == "" || len(p) > 3 || (len(p) > 1 && p[0] == '0') {
return status{}, false
}
for _, c := range []byte(p) {
if c < '0' || c > '9' {
return status{}, false
}
n[i] = n[i]*10 + int(c-'0')
}
}
if n[0] != 2 && n[0] != 4 && n[0] != 5 {
return status{}, false
}
return status{n[0], n[1], n[2]}, true
}
I tested it against each row of the table, a set of malformed codes and a fuzz target, and it passes go vet, go test -race and a 30-second fuzz run on Go 1.27.
Anything the classifier doesn’t recognize returns Review and stays off the list until someone looks. A broken status lands there too, with an error. RFC 3464 says each sub-field “MUST be expressed without leading zero digits”, and a parser that reads 5.01.1 as 5.1.1 would suppress an address on a misreading. A missed suppression costs one more bounce. A wrong one costs a person who never hears from that sender again, and nobody finds out.
Complaints and the message id #
A complaint uses the Abuse Reporting Format from RFC 5965, the same multipart/report shape with a message/feedback-report part in the middle. It doesn’t need classifying. Someone said they didn’t want the message, and the platform stopped sending them that client’s mail.
Matching either kind of notice to a message takes more than Final-Recipient. Forwarding and aliases change the address, some feedback providers redact it, and the notice doesn’t say which client sent the message.
So every message carried a header of the platform’s own with its message id, call it X-Message-Ref. RFC 6449 recommends the same thing. The Lambda read the id from the third part, and from it the platform knew the client and the exact address. In a bounce that third part is optional, and without it the only match is Final-Recipient. VERP avoids that by writing the recipient into the envelope sender itself. This platform kept the id in a header.
One list per client #
A complaint about one client’s newsletter says something about that newsletter and that person. It says nothing about a password reset from another company on the same platform. RFC 6449 puts it as “Suppressing the address across an entire ESP is likely too broad.” The cost is that a dead mailbox is dead for everyone, and each client learned that with a bounce of its own. Sharing 5.1.1 across clients would remove that cost and let one client’s bad data reach the others. We stayed per client.
The check in the sending path #
Before accepting a message, the API looked up each recipient for that client. A recipient on the list never got a queue entry or an MTA connection. The API was internal, so it refused the request, said the recipient was suppressed, and let the caller decide.
When the lookup failed, the API didn’t send. That ties sending to DynamoDB being up, and I chose it. A message held back can go out later. A message delivered to an address we already knew to avoid can’t be called back.
The check doesn’t stop a message already in a queue. The API reads the list on accept, the MTA delivers later, and with Postfix’s default maximal_queue_lifetime of five days that gap can be most of a week for a recipient that keeps deferring.
The feedback path #
The Return-Path domain was a verified SES identity with an MX of 10 inbound-smtp.<region>.amazonaws.com, as SES email receiving asks. A receipt rule stored each message in S3, one object per message. Before any rule runs, SES drops mail from “addresses on the block lists of either Spamhaus or SES”, and there are “no logs that show which IP addresses are being blocked”. A notice from a listed MTA disappears without a trace.
Storing first kept the raw notice, so a classifier change could run again over old ones. SES has a suppression list of its own, but it acts on mail SES sends. Here SES only received, so the list that mattered had to be ours.
The Lambda reads each new object, walks the MIME parts, classifies and writes. S3 delivers event notifications “at least once”. Lambda invoked this way retries a failed event two more times by default and drops it after three failures or six hours, unless a dead-letter queue or an on-failure destination keeps it.
Duplicates don’t hurt a suppression, since writing the same key twice leaves one entry. They do hurt a counter, because a duplicate counts a failure twice and brings a suppression forward. The counter has to remember which notices it already counted and do that in the same write as the increment, with a conditional update that records the S3 object key or a transaction. A lost event is a suppression that never happens. The object is still in S3, and an S3 Inventory of the bucket checked against an export of the table now and then finds what slipped through.
What the providers ask for now #
Since February 2024 Gmail and Yahoo ask bulk senders for roughly this loop and more. Gmail wants the spam rate in Postmaster Tools “below 0.10% and avoid ever reaching a spam rate of 0.30% or higher”. Yahoo’s best practices ask for under 0.3%. Microsoft announced in April 2025 that domains sending more than 5,000 messages a day to Outlook.com must pass SPF, DKIM and DMARC, with rejections that carry 5.7.515, a 5.7 refusal about the sender that a classifier must not read as a dead address.
Gmail’s complaints don’t come back per message. Its feedback loop reports aggregated spam rates per Feedback-ID on a dashboard. At Gmail this loop learns from bounces alone. The per-person signal Gmail passes on is the one-click unsubscribe from RFC 8058, an HTTPS POST that arrives outside the email path in the diagram.
What this doesn’t cover #
There are no figures from the platform here. No bounce rate before or after, no count of suppressed addresses, no lookup latency, no threshold for temporary failures. It describes a design and doesn’t measure its effect. The classifier reads only Status, so dead addresses at Microsoft and Yahoo wait for a person or for text matching this post doesn’t write. The counter has no reset. Gmail complaints never reach a per-address list. Unsubscribes and the way back for someone who wants mail again after being suppressed aren’t covered, and the gap between accepting and delivering stays open.
If you run a loop like this and handle 5.7.1 or the deferral codes differently, I’d like to hear what you saw.