Every production email program needs a record of what happened after send. Providers expose that record through webhooks, exports, activity APIs, or stream-style feeds. The ingestion design has to handle duplicates, late arrivals, terminal states, and different retention windows.
last updated 2026-05-074 sections
section 01
Event types and state
Delivery events are not all equal. Delivered, bounced, complained, unsubscribed, opened, and clicked should not overwrite each other blindly. Terminal events such as hard bounce and complaint should win over later engagement noise.
event
state effect
terminal
delivered
Mailbox provider accepted the message.
No
deferred
Temporary delivery delay.
No
hard_bounce
Address should be suppressed.
Yes
complaint
Recipient marked mail as spam.
Yes
unsubscribe
Recipient opted out of marketing.
Yes for that stream
open or click
Engagement signal if tracking is enabled.
No
section 02
Push, pull, and export patterns
Webhooks provide low latency but require a public endpoint and retry handling. Pull APIs simplify firewall rules but add polling lag and retention risk. Exports work for audits and backfills, not live suppression.
pattern
fit
main risk
Webhook push
Live delivery state and suppression updates.
Endpoint outage causes retry backlog.
Activity API pull
Small teams and periodic sync.
Missed records when retention is short.
Bulk export
Audit, warehouse backfill, and reporting.
Too slow for operational suppression.
section 03
Ordering and dedupe
Email events can arrive out of order. A click can arrive before delivered. A bounce can be retried several times. The consumer should dedupe by provider event ID when available, then apply state transitions with precedence rules.
okStore raw events before applying message state.
okUse a unique event key to make retries harmless.
okDefine terminal state precedence before launch.
okAllow late events to enrich history without changing terminal state.
section 04
Downstream uses
Event streams feed suppression, support debugging, customer timelines, deliverability monitoring, and revenue reporting. Each use has different latency needs. Suppression should be near-real-time. Analytics can tolerate batch sync.