Delivery Events and Diagnostics

When you need to know what happened to a message, or why a campaign is underperforming, the answer starts in the event stream. Every message an email service provider (ESP) handles passes through a series of states. Each change of state is an event that the platform records and can stream to you.

Bounce and complaint rates, estimates of inbox placement for each provider, delay analysis and engagement scores are all built from these events. The SendGrid Event Webhook is used below as the reference example, because it is fully specified. After the events come the reporting, delay diagnosis and engagement scoring built on them.

For the thresholds these events feed and the corrective actions they trigger, see Metrics and Benchmarks. For step-by-step diagnosis, see Delivery Troubleshooting Playbooks. Both rely on the data described here.

The event taxonomy

Events fall into three families. Delivery events record what the sending system and the receiving servers did with the message. Engagement events record what the recipient did. Account events record changes of status at platform level. SendGrid's Event Webhook posts these as JSON. The names are SendGrid's labels, but every sending infrastructure produces equivalent states.

Delivery events

The distinctions an operator needs to know well:

• A deferral is not a bounce. A deferral is a temporary refusal that the platform keeps retrying. It becomes a bounce only if the retries run out. Persistent deferrals are the classic sign of throttling or rate limiting (see Delay and latency diagnosis).
• Bounced and blocked are different. SendGrid records both as a bounce event and tells them apart with the type field. type: "bounce" is a hard bounce, which is permanent (for example, the address does not exist). type: "blocked" is a soft bounce: a temporary rejection because of reputation, content or a technical problem. In the Bounces & Blocks reports in the interface, a Bounce means an invalid email address (one that never existed or was deactivated), while a Block means the message was rejected for "content and reputation issues or technical failures." A block is the receiver's judgment of you, not of the address, and it can clear once the reputation or content problem behind it is fixed. See Blocklists and Spamhaus.
• A drop is the platform protecting you, or your own mistake. The platform suppressed the send before transmitting it. Most drops are healthy, because suppressing a known-bad address protects reputation. A spike in drops for unexpected reasons (an invalid template, an exceeded quota) points to a defect on the sending side, not to a problem at the receiver. Suppression-List Architecture explains how suppression is scoped.
• Delivered does not mean in the inbox. delivered is posted when the receiving server answers 250 OK. After that, the receiver may still put the message in the inbox, queue it, file it in the spam or junk folder, drop it silently, or (at Gmail) sort it into a tab, and the sending platform receives no further signal about any of it. The only later evidence is recipient engagement (opens and clicks). A high delivered rate with near-zero engagement is the typical sign of mail going to the spam folder. This is why inbox placement can only be estimated, with seed tests and provider postmaster dashboards, and never read directly from the delivery events. See Tracking and Measurement Distortion and Reputation Monitoring.

Bounce classification

For bounce events, SendGrid adds a bounce_classification that places the SMTP failure in a category of cause an operator can act on:

The Content and Reputation categories feed engagement quality scoring (below) as an early warning, because they show that the receiver is judging you, not that the address is bad.

Engagement events

Two cautions keep the engagement events from misleading you:

• Machine opens. SendGrid sets sg_machine_open: true when Apple Mail Privacy Protection (MPP), rather than a person, generated the open. Filter these out of any real measure of engagement. Gmail's image prefetching also triggers opens without a person. See Tracking and Measurement Distortion and Non-Human Interactions.
• spamreport is your complaint signal. It is the part of the provider feedback loop that the sender sees. A sustained spamreport rate is the most damaging single input to reputation. See Complaint Feedback Loops.

Account events

SendGrid emits account_status_change when the platform changes an account's standing for compliance reasons (phishing, high spam rates, "other bad behavior"). The type field gives the action, in increasing severity:

For how an ESP operator detects and contains these problems and applies the enforcement ladder, see Compromised Accounts, Outbound Monitoring and Multi-Tenant Architecture.

Event payload fields

The webhook JSON has a common set of fields plus fields specific to each event. These are the fields you correlate to answer "what happened to this message?"

SendGrid warns never to put personal data in category or unique_args. The platform may use these fields for internal operations, they cannot be redacted, and they may be kept for a long time.

A typical diagnostic query joins all events that share an sg_message_id and sorts them by timestamp to rebuild the full history of one message: processed, then deferred one or more times, then delivered, then opened. Another aggregates by event, bounce_classification and receiving domain to find which provider is rejecting which category of mail.

Deliverability-insights reporting

A diagnostic dashboard built from the event stream follows the "Deliverability Insights" pattern (in SendGrid, under Stats, then Deliverability Insights). Its data is roughly 48 hours behind real time. It has four views:

The most important design choice is segmenting by mailbox provider. A combined delivered rate of 95% can hide a complete block at one provider. Reputation is held separately at each provider, so diagnosis and remediation must be done provider by provider too (see Reputation Monitoring and Per-Provider Tuning Baselines). SendGrid publishes these thresholds for reading this view:

These are consistent with the thresholds gathered from several sources in Metrics and Benchmarks: the consensus of ≤0.1% complaints and <5% bounces, and the 0.3% line that Gmail and Yahoo treat as a violation.

Delay and latency diagnosis

"Delay" can mean two very different things, and confusing them sends the diagnosis in the wrong direction.

1. Delay at the receiver (deferrals and throttling). The message has left the platform, but the receiver is holding it back through greylisting, rate limiting or "try again later". This shows up as deferred events with a rising attempt count and a 4.x.x response. The platform retries on a schedule. SendGrid retries deferred messages for up to 72 hours, then turns the message into a bounce.

Persistent deferrals concentrated at one provider mean you are going beyond what that provider accepts in rate or volume. The remedy is to shape traffic for that receiver (reduce concurrency or rate, spread the send over more hours), not to retry more. See MTA Delivery Tuning and Greylisting (RFC 6647).

2. Delay on the platform or at injection (stuck in Processing). The message never reaches a receiver; it stays in the processed state. SendGrid documents several causes:

• A volume limit on a new dedicated IP address. A volume cap applies for the first 3 days on a new dedicated IP address, to prevent abuse. Increase volume gradually with the IP warm-up process.
• A compliance hold. For an account under review, or one where unusual activity was detected, sending is paused until the Compliance team confirms.
• Backpressure in the MTA queue. Very high sending volume can back messages up in the outbound MTA queue. Pause sending or bring another IP address online.
• Suspension of a dormant account. Accounts with no logins are suspended automatically.

Messages stay pending for up to 72 hours. If the underlying problem is not resolved by then, they become hard bounces.

3. Transport latency (integration and network). The message is slow getting into the platform. SendGrid's guidance focuses on throughput and the network path:

• Use the official client libraries (C#, PHP, Ruby, Node.js, Python, Go, Java) rather than code written from scratch.
• SMTP throughput: up to 5000 messages per connection, and up to 1000 To: recipients per message (through the x-smtpapi header).
• Open more concurrent connections, up to a recommended maximum of ~10 concurrent connections.
• Network diagnostics: hping and Test-NetConnection measure response time and TTL, and anything above ~150 ms of response time is a first warning sign. Traceroute mode shows the latency at each hop; watch for sudden jumps between hops. Header analyzers (such as Google's) show the message's path through each MTA and how long it waited at each hop. Wireshark captures the SMTP conversation for close inspection.

Diagnose in this order. Check the event state first. processed points to a platform or compliance issue; deferred points to throttling by the receiver; delivered but no engagement points to the spam folder, which is a placement problem, not a delay. Use transport latency tools only once you have confirmed the message is leaving the platform normally.

Engagement-quality scoring

The highest level of aggregation turns the whole event stream into a single health score. SendGrid's Engagement Quality (SEQ) API is the reference example. It returns a score from 1 to 5, where higher means better engagement and deliverability. The score lets an operator rank senders and subusers at scale and spot a decline before it becomes a reputation incident.

A score is generated only with open tracking enabled and ≥ 1,000 messages sent in the previous 30 days. Scores are kept for a maximum of 90 days. The endpoints return scores for the account and for each subuser.

The score combines five weighted components, which are the event signals described above, condensed:

The design shows what a platform actually treats as quality: recent engagement (are you mailing people who still want the mail?), real rather than machine opens at the providers that matter, permanent bounces moving in the wrong direction, reputation and content bounces in particular, and complaints. An ESP can use these scores to group subusers into IP pools, flag underperforming senders for outbound monitoring, and decide when to move senders between shared and dedicated infrastructure.

Related articles

• Delivery Troubleshooting Playbooks
• Metrics and Benchmarks
• Enhanced Status Codes (RFC 3463), for reading the status field
• Delivery Status Notifications (RFC 3464), the format of asynchronous bounces
• Tracking and Measurement Distortion, on why opens and clicks mislead
• MTA Delivery Tuning
• Complaint Feedback Loops (RFC 6449)
• Reputation Monitoring