Bounced, blocked or dropped: what SendGrid's event feed tells your app to do

The feed is the only record of what happened

When your app calls the mail send endpoint it receives an accepted response and nothing more. Everything afterwards, whether the receiving server took the message, deferred it, rejected it or never saw it, reaches you only through the event feed, if you turned it on and if your endpoint is recording it. Without that, a customer who says a message never came cannot be checked against any record.

• Processed: SendGrid took the message and can deliver it.
• Deferred: the receiving server temporarily rejected it.
• Delivered: the receiver accepted it.

Bounce, blocked and dropped mean different things

A bounce event carries a type field. The documentation calls a bounce a permanent rejection and a block a temporary one that the receiver might accept later. A dropped event means SendGrid itself did not send, for reasons including an address that previously bounced, reported spam or unsubscribed, an invalid header or an exceeded quota. Treat them differently: flag an address after a permanent bounce, watch repeated blocks before flagging, and read the reason of a drop because it may point at your own request rather than the recipient.

• Store the reason text and the classification field exactly as reported.
• Do not delete the address record; flag it so an admin can clear the flag.
• A drop for a prior bounce means your own flag did not exist or was ignored.

Store each event once

Events can be repeated, and SendGrid retries a delivery to your endpoint for up to a rolling day if you do not return a success status. The documentation tells you to deduplicate on the unique event ID. A table with a uniqueness rule on that ID makes a replay harmless. The same table gives support a history: for a given address, every event in order, with the reason the receiving server gave.

• Return a 2xx only after the event is stored or deliberately skipped.
• Never put personal data into custom arguments or categories; the page advises against it.
• Keep the table small: event ID, message ID, address reference, type, reason, time.

Test with deliberate bad recipients, safely

Send a message to a recipient that cannot exist, on a domain you control, from a staging copy of the app. Check that exactly one record appears, replay the same payload and check it still holds one, then send again to that address and confirm the app skips it and logs the skip. Never use real customers' addresses for this, and use a test integration button or captured payload only for plumbing, not as proof of signature handling.

How the paid outcome is accepted

The SendGrid outcome for up to three message types is accepted when the bounce test above produces one stored record, a replay leaves one, a forged request changes nothing and a later send to the flagged address is skipped. The fixed £395 price is untested and payment follows sign-off. The monthly delivery review is the standing service for the records that this creates.