Message ID Receipts for Node.js Transactional Email: Delivered or Bounced?

Node.js transactional email dashboards should poll the mail transport through a SaaS-owned endpoint, using the SaaS message ID. This approach prevents user traffic from being coupled to rate limits and prevents incomplete upstream timelines from becoming the application's truth. The dashboard reads a local projection of sent, delivered, and bounced states, which are stored as immutable receipts under the message ID.

A one-to-one mapping of logical message to transport message ID is not advisable, as each attempt may receive a different transport ID.

Receipts should be stored as immutable observations with a one-to-one mapping between internal message ID, attempt number, transport ID, source event ID, normalized kind, source timestamp, ingestion timestamp, and a sanitized copy of the original payload. Unique constraints should be applied to the source event ID within its transport account. If source event IDs are unstable, use a documented deduplication fingerprint instead.

The read model should expose a current state, last_event_at, attempt count, and a short timeline. Unknown event kinds should be preserved rather than guessed based on elapsed time. This approach allows for handling edge cases like retries, bounces, and multiple tabs requesting status simultaneously. The dashboard should show the latest successful attempt for a logical message while retaining the history of previous attempts.

Email events can be duplicated, delayed, or delivered out of order. A reducer should be used to project receipts into a state machine, handling duplicates and disorder. The reducer should be transport-neutral and refuse to manufacture progress from unfamiliar receipts. It should also separate authentication logic from delivery evidence to maintain security. The reducer should be thoroughly tested with various edge cases and stored transactions.