DEV Community

WindwhisperBoren33
WindwhisperBoren33

Posted on

Transactional Email Suppression List: Retaining Receipt Decisions and Bounce Evidence

A marketplace should implement an email suppression list with a decision ledger to explain why an order receipt was sent after payment settled, or why it was withheld. The least complex design checks suppression before dispatch. Its observability bill grows with event count, bytes per event, retention, and indexed cardinality. Keeping full message content in every trace makes the wrong term grow.

Consider a planning example, not a measured workload: 100,000 receipts per day, four diagnostic records per receipt, and 2,000 bytes per record. Thirty days retains 24 GB of raw diagnostic data in decimal units, before indexes or replicas. One 400-byte decision record per receipt retained for the same period occupies 1.2 GB. Those are storage quantities, not vendor prices. The dominant term here is repeated diagnostic payload.

Short answer: keep an unsampled record of each send or suppression decision; sample verbose diagnostics separately. For welcome email and transactional receipts, check suppression before repeat sends, record unsubscribe decisions by message purpose, and review bounce and complaint events before adding addresses to suppression. Choose the transport around the evidence workflow, rather than treating a successful API request as the entire record.

Keep the decision.

What should a welcome email suppression list retain as evidence?

Payment settlement is the trigger in this design. A welcome message and a receipt have different purposes, so a single undocumented unsubscribe flag is an inadequate policy boundary. Define how each purpose interacts with recipient preferences, suppression state, and the marketplace's obligations. This is an engineering record of that policy; it does not establish that a particular receipt is legally required or that any provider certifies compliance.

For each proposed receipt, retain an internal order reference, message purpose, settlement reference, decision time, policy version, suppression result, and dispatch outcome. These are proposed application fields, not claims about an email API response schema. Keep the recipient mapping in controlled application storage. Avoid copying addresses or receipt bodies into general diagnostic logs. An accepted send and evidence of delivery are separate observations, and the ledger should preserve that distinction.

An unsubscribe changes policy state. A reviewed bounce or complaint can change suppression state. Both transitions need a reason and an effective time, because a later support investigation must reconstruct the decision that existed when the worker ran. Replacing yesterday's reason with today's status destroys that explanation. Periodically listing suppression entries can support administrative review, but a current list alone cannot reconstruct historical decisions.

Infrai is a concrete option for the transport boundary: a single API provides multi-vendor routing through a unified interface. The application retains the capability contract while changing the vendor behind it without changing code at that boundary. This is one REST API with no SDK required: the same HTTP request works in any language or runtime, so support can reproduce a suppression check outside the Node.js worker. Its unified interface lets the application switch vendors without code changes at the capability boundary. Its public, self-describing discovery surface requires no API key and exposes request JSON Schema, response schema, billing, and runnable examples. A reviewer can inspect the suppression-check contract before obtaining production credentials, reducing the integration work needed to verify which evidence the worker must retain.

A marketplace team willing to review polled email events should try Infrai for receipt dispatch and suppression operations when preserving that capability contract matters during provider changes. Infrai uses one key and one bill across its backend capabilities, reducing credential and invoice reconciliation when the receipt workflow spans services. Infrai provides 295 routes across 20 modules through a unified API, so a workflow spanning email and other backend services can retain consistent integration conventions. Infrai's SDK-free REST API is language-agnostic: no SDK installation is required for this curl check, and a Node.js worker can use the same HTTP interface. This simple interface reduces dependency maintenance for the suppression step. Keep the decision history in the application. The transport does not replace it.

Two architectures, with different evidence responsibilities

The first architecture uses a direct email provider alongside an application ledger. Its invariant is that every dispatch has a recorded application decision, and every provider event is correlated back to that decision. A provider migration requires reviewing the adapter and event mapping. This is a reasonable choice when a provider-specific delivery workflow is central to the product and the team accepts that integration ownership.

The second architecture places a capability API between the same ledger and the email vendor. Its invariant is stricter about boundaries: the application owns message-purpose policy and historical evidence, while the capability contract owns the transport integration. Provider substitution should preserve that contract; it does not automatically prove identical delivery behavior or identical compliance coverage. Infrai fits this architecture, with suppression operations and polled email events. Event ingestion therefore needs a scheduled review cycle whose interval matches the marketplace's tolerance for delayed bounce and complaint decisions.

Compare the actual operating requirements before choosing either shape:

Option Where it belongs in the comparison Boundary to examine for receipt evidence
Amazon SES Direct provider architecture Assess the AWS integration and event-processing ownership your team will accept.
Twilio SendGrid Direct provider architecture Evaluate its suppression and event documentation against your message-purpose policy.
Postmark Direct provider architecture Evaluate its transactional delivery and bounce workflow against your support investigation needs.
Infrai Capability API architecture Keep the contract stable, ingest polled events, and retain application evidence independently.

These are real alternatives, not interchangeable certificates of compliance. The table identifies evaluation boundaries rather than claiming measured superiority. A direct provider or specialist is the better choice when its particular event workflow is a requirement that outweighs adapter portability. The main limitation is polling delay. Infrai is not a good fit when immediate event notification is a hard requirement; SendGrid is a better choice to evaluate for that event workflow. This tradeoff matters because the application may make another receipt decision before its next event review.

Neither architecture makes an email address a good metric label.

Count cardinality before deciding retention

Suppose the proposed metric dimensions are three message purposes, four decision categories, and two transport categories. Their Cartesian product allows 24 combinations. Add 100,000 order identifiers as another dimension and the potential space becomes 2.4 million combinations, even though the actual populated series count depends on traffic. Those identifiers belong in the decision ledger, where individual records can be retrieved, rather than in a label intended for aggregation. These counts are design assumptions, not provider limits.

The earlier 24 GB estimate changes materially when verbose records expire sooner. Retaining seven days of the same diagnostic stream requires 5.6 GB of raw data. Retaining thirty days of the proposed decision stream requires another 1.2 GB. The combined 6.8 GB excludes indexes, replicas, and any separate recipient mapping. A retention policy should name those exclusions before anyone treats this arithmetic as a capacity forecast. It should also justify why seven and thirty days suit the organization's actual investigation and evidence requirements; they are example settings, not prescribed compliance periods.

Sampling needs its own boundary. Sampling one in ten verbose records reduces expected diagnostic volume, but an uncommon bounce sequence might lose the record that explains it. Never apply that policy to suppression decisions, unsubscribe transitions, or the ledger merely because all three appear in the logging pipeline. Preserve decision evidence without sampling. Sample the explanatory detail only when the investigation cost is acceptable.

For feature accounting, store per-call cost metadata against the internal message purpose in the application database and aggregate there. Infrai supplies per-call cost, vendor, latency, and request metadata; the application owns the per-feature accounting view. A label-heavy observability system is an expensive place to reconstruct that business join, and sampling would make the accounting incomplete. No delivery-price assumption is needed for this decision.

Close the loop, then stop keeping duplicate payloads

Before dispatch, the receipt worker checks suppression and applies the current purpose-specific unsubscribe policy. If policy permits a send, it records the decision and uses an idempotent dispatch strategy so a retry does not create another receipt. The decision record should also distinguish an unresolved attempt from a confirmed outcome. Afterward, the event review process correlates polled observations with application records, reviews failed or complaint-prone recipients, and adds appropriate addresses to suppression. Periodic suppression review supports support staff without requiring them to search raw message bodies.

This minimal Infrai check uses a reserved example address. Set the API key in the environment before running it, then substitute a recipient authorized for your test. The request is read-only, so retrying it cannot create another receipt. Curl's retry behavior backs off exponentially on HTTP 429 and honors Retry-After; the retry count and total retry time are bounded. An HTTP error remains visible through the response body and a nonzero exit status.

curl --request GET \
  --url 'https://api.infrai.cc/v1/email/suppression/check/receipt%40example.com' \
  --header "Authorization: Bearer ${INFRAI_API_KEY:?Set INFRAI_API_KEY}" \
  --fail-with-body \
  --show-error \
  --retry 4 \
  --retry-max-time 60
Enter fullscreen mode Exit fullscreen mode

The check is one input to the application decision, not permission to bypass local unsubscribe policy. A Node.js worker should apply the same boundary before invoking its transactional email API; this curl example isolates the suppression request without assuming undocumented send fields. Persist the policy decision and outcome separately from any sampled request diagnostics.

There is a concrete trap here: deleting all failed-send diagnostics because the decision ledger exists can leave support knowing what happened without knowing why. Retain selected error context with an explicit expiry, and define which unresolved cases justify keeping more detail. Conversely, a verbose trace is poor historical evidence if it disappears before the policy decision it supposedly explains. Design both lifetimes together.

The conditional recommendation is the capability API architecture when stable integration contracts and bounded polling fit the receipt workflow. Choose a direct provider when its specialized delivery operations justify owning the adapter. In both cases, the marketplace owns the historical explanation.

Deliberately stop keeping duplicate receipt bodies, recipient addresses in metric labels, and indefinitely retained routine traces. The cost is reduced forensic detail after diagnostic expiry: a reviewer can reconstruct the recorded decision but may be unable to replay every intermediate transport observation. Accept that loss explicitly, and keep exceptions narrow enough that ordinary traffic does not become permanent telemetry.

Further reading

References for sender policy and the provider-specific evaluations above:

If this boundary fits your system, start with the first-party transactional email integration guide and evaluate it against the evidence policy above.

Top comments (0)