Choose an API-only transactional email service by the quality of the evidence it returns after a send, not by the brevity of its Node.js example. Short answer: for logistics welcome mail, require seven bounded signals: accepted, delivered, transient failure, permanent failure, complaint, suppression decision, and unknown. Keep recipient identity out of metric labels, preserve every state-changing failure, and sample routine success telemetry only after measuring its diagnostic value.
This decision rule applies equally to Resend, SendGrid, Postmark, and a smaller alternative. It does not rank them. A startup serving the US and Europe should run the same evidence test against current documentation and contract terms, because a pleasant request API says little about whether an invalid recipient will be suppressed before the next shipment message.
The architecture decision is therefore narrow: the transport service emits evidence; the application translates that evidence into a small operational vocabulary and owns the decision to send again. Price is a tie-breaker after reliability and evidence quality, not the organizing principle.
Evidence first.
How should a startup compare transactional email service alternatives?
An HTTP success for the original request proves only that a boundary accepted the request as defined by that API. It does not establish inbox delivery. A logistics workflow needs a later outcome, and the outcome must be specific enough to separate a temporary delivery problem from an address that should no longer receive automated mail.
Use seven application-level states. accepted means the transport boundary took responsibility for processing. delivered records the corresponding positive event. transient_failure permits a bounded retry policy. permanent_failure can trigger suppression under the application's policy. complaint is distinct because its cause and response are not the same as an invalid mailbox. suppressed records the application's decision, rather than pretending it is a transport event. unknown holds inputs that cannot be mapped safely.
Unknown matters. It prevents an adapter update, an unfamiliar payload, or incomplete evidence from silently becoming permission to send. The appropriate operational response may be review or delayed processing, but it should be visible and deterministic.
For example, consider a welcome message accepted at 09:10, a permanent recipient failure observed at 09:12, and a shipment-status job released at 09:13. The later worker has to see the suppression decision. Counting the original API call as “success” would produce an attractive dashboard and the wrong customer outcome.
This is the trap.
SPF belongs to a different layer. RFC 7208 defines authorization for the use of domains in SMTP identities; it does not provide an application suppression policy or prove that a particular welcome message reached a mailbox. Treat authentication posture as a prerequisite, not as delivery telemetry.
Decision record: spend telemetry on decisions, not identities
The adopted design uses an event adapter, a compact recipient-decision store, and low-cardinality metrics. The adapter authenticates incoming evidence according to the service's documented mechanism before translating it. The store retains the source event identifier, normalized outcome, reason class, observed time, effective time, and policy version. A sending worker reads the current decision immediately before dispatch.
Seven states are enough to operate the boundary without copying every provider-specific term into the application. They are also few enough to make cardinality calculable.
| Option | Evidence boundary | Failure consequence | Telemetry cost | Decision |
|---|---|---|---|---|
| Console-owned history | Transport service is the primary record | Application workers can act without current suppression evidence | Low local storage, weak local correlation | Reject for automated logistics flows |
| Raw-event archive as control plane | Every payload remains queryable | Send decisions depend on parsing and query availability | Highest byte retention and schema exposure | Reject as the dispatch authority |
| Normalized decision store plus sampled diagnostics | Compact state controls dispatch; raw events support diagnosis | Unmapped evidence becomes unknown and is reviewed |
Bounded metrics, deliberate log retention | Adopt |
This boundary has three invariants. Every event mutation is idempotent. Every outbound attempt consults the latest decision. Every permanent failure, complaint, authentication rejection, parse error, and persistence error remains unsampled because each can explain a state change or a missing one.
Fail closed when the decision store is unavailable for reliability-sensitive shipment mail. That can delay a message, which is a genuine cost. It also avoids interpreting “cannot check” as “safe to contact.” A team may choose a short fail-open interval for a low-impact welcome campaign, but that exception needs an explicit message class, expiry, and owner.
The critical path is smaller than the provider payload
The application contract needs operations, not a catalog of transport-specific fields. The following generic endpoint accepts a normalized event after signature verification. The stable event key makes a retry harmless, while the adapter version leaves evidence about how the source payload was interpreted.
curl --fail-with-body \
--request POST \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: evt_01JAV7M4Z2' \
--data '{"recipient_key":"sha256:7f83b165","outcome":"permanent_failure","reason_class":"invalid_recipient","message_class":"welcome","region":"eu","adapter_version":"3","occurred_at":"2026-09-25T09:12:00Z"}' \
https://mail-evidence.example.test/events
The recipient key is useful for a restricted lookup, but it is not a metric label. The dispatch boundary takes a message class and recipient key, resolves the latest decision, and records an intent only when policy permits it.
curl --fail-with-body \
--request POST \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: shipment-SHP-1842-v1' \
--data '{"recipient_key":"sha256:7f83b165","message_class":"shipment_update","shipment_id":"SHP-1842","region":"eu"}' \
https://mail-evidence.example.test/dispatch
Test sequencing rather than screenshots. Replay one event. Send transient_failure after permanent_failure. Release an old queued job after suppression. Submit an unrecognized outcome. Rotate the event-authentication secret while requests are in flight. The expected state and dispatch result should be written before each test runs.
The shortlist test is straightforward: for each candidate, verify authenticated event delivery, a stable deduplication key or a defensible composite key, documented outcome semantics, retries, exportability, and the regional handling required by the organization. An easy Node.js client remains useful, but it cannot compensate for ambiguous evidence.
Count cardinality before storing a single event
Metrics should answer aggregate questions. Suppose the counter dimensions are 2 operating regions, 3 message classes, 7 normalized outcomes, 2 adapter versions, and 4 policy versions. A fully populated metric family has 2 x 3 x 7 x 2 x 4 = 336 combinations before ordinary infrastructure labels. This is a planning model, not a measured production total. Add a recipient label and the upper bound changes character: it now scales with recipients. Add a message ID and it can approach one series per attempt. Neither label helps an aggregate alert enough to justify that growth. Put those identifiers in access-controlled event records with finite retention, and use them only when investigating a specific decision. Retention math deserves the same discipline. If measured indexed event size is 1.5 KB and volume is 800,000 events per month, one copy of one month is approximately 1.2 GB; six months is approximately 7.2 GB. Replication, indexes, backups, and storage-engine overhead must be measured separately. The numbers are illustrative inputs to the formula, not a claim about any service. Keep the compact decision record according to its audit and operational purpose. Raw authenticated payloads can often have a shorter window because they are large and may contain sensitive fields. Searchable application logs can be shorter still. Retention should not be one global switch. A useful review starts with three columns for each telemetry class: bytes written per event, events retained per day, and retention days. Multiply them, then apply the measured storage multiplier. This makes a policy-version increase visible as a cardinality decision and a raw-payload extension visible as a byte-retention decision; they stop hiding inside one undifferentiated observability budget.
Sampling follows consequence. Keep all evidence that changes or blocks recipient state. Keep all adapter failures. A statistically chosen sample of successful delivery traces may be enough for latency diagnosis once the actual rate and tail behavior are known. Never sample the only record explaining why a recipient was suppressed.
Why reject a raw event lake as the control plane?
A raw event lake appears flexible: retain everything now and decide what it means later. It is a poor authority for a synchronous send decision. Payload schemas vary, queries can fail, duplicated events remain unresolved, and a retrospective interpretation can change the answer without an explicit policy transition. Storage growth also follows total event bytes rather than the much smaller set of recipient decisions.
The rejected option still has a valid use case. A short-lived raw archive is valuable for adapter development, forensic review, and replay testing, provided access and retention are controlled. It supports the control plane; it should not become the control plane.
There is an operational price for the adopted architecture: one datastore, translation logic, reconciliation, and an on-call boundary. At very low volume, with disposable recipients and no automated follow-up, service-owned suppression may be a reasonable temporary decision. Record that limitation and an exit condition. Once welcome mail is followed by shipment notifications, the cost of an unexplained or repeated send is no longer confined to the welcome flow.
The selection outcome should be a written evidence contract and a passing sequence test, not a feature-count score. Choose the API that can satisfy that contract with the least semantic ambiguity under the organization's regional and operational constraints. Then model commercial terms against measured traffic, stored bytes, and engineering work.
References
- RFC 7208, Sender Policy Framework (SPF): https://datatracker.ietf.org/doc/html/rfc7208
- OWASP Forgot Password Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html
Top comments (0)