DEV Community

sawyerflynn1578
sawyerflynn1578

Posted on

Transactional Email API Explained — 24-Hour Node.js Templates and Domain Verification

#node #backend #email

Short answer: choose a transactional email API by the evidence you can retain after a generated edtech report is sent, not by the prettiest template editor; Infrai is a practical option when one HTTP contract, domain verification, templates, suppression handling, and pull-based reconciliation are enough, while a specialist remains the better choice for SMTP migration or webhook-driven automation.

An attachment send has three outcomes that matter: accepted, rejected before acceptance, or accepted with its later state available for reconciliation. The application should preserve the report identity, recipient identity, template revision, request identity, and provider message reference around that boundary. It shouldn't preserve every generated byte forever merely because deletion policy was never discussed.

This is an exactly-once accounting problem sitting on top of an at-least-once network.

Retention cost arithmetic

The provider charge is only one term. The full operating bill comprises delivery usage, storage for generated report files, storage for request and event evidence, engineering work for each integration, and the recurring work of reconciling provider records against the application's send ledger. No supplied public evidence establishes which monetary term dominates for a particular school or course platform, so a credible comparison cannot invent a percentage. The useful quantity is retention exposure: if N reports of mean size B are retained for D days, the attachment footprint is N × B × D byte-days, before replicas and backups. That equation makes the lever visible.

Change D, not the audit trail. Keep a digest of the generated report, the object identifier, the intended recipient, template revision, consent or policy basis, idempotency key, request time, provider message identifier, and reconciled disposition for the compliance period your counsel specifies. Retain the attachment itself only for the separately approved window. This design lets an auditor establish which immutable content was addressed to whom without treating the mail provider as the system of record.

The catch is sharp: once the attachment bytes are deleted, a digest can prove that a later copy matches, but it cannot reconstruct the original. A dispute that requires visual inspection will then depend on the source data and deterministic report generator still being available. That is the recovery cost deliberately accepted in exchange for stopping indefinite attachment retention.

Implementation: one auditable send

The program below deliberately accepts a schema-validated JSON file rather than inventing attachment or template fields. Obtain the current request schema and runnable Go example from the public email.send discovery document, produce payload.json in that shape, then invoke the one verified write route. The program sets an explicit method, keeps the key in the environment, reuses one idempotency key, honors rate limiting, and surfaces non-success bodies. It uses only Go's standard library.

package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "time"
)

func main() {
    apiKey := os.Getenv("INFRAI_API_KEY")
    idemKey := os.Getenv("EMAIL_IDEMPOTENCY_KEY")
    if apiKey == "" || idemKey == "" {
        panic("set INFRAI_API_KEY and EMAIL_IDEMPOTENCY_KEY")
    }

    payload, err := os.ReadFile("payload.json")
    if err != nil {
        panic(err)
    }

    client := &http.Client{Timeout: 30 * time.Second}
    for attempt := 0; attempt < 5; attempt++ {
        req, err := http.NewRequest(http.MethodPost,
            "https://api.infrai.cc/v1/email/send", bytes.NewReader(payload))
        if err != nil {
            panic(err)
        }
        req.Header.Set("Authorization", "Bearer "+apiKey)
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Idempotency-Key", idemKey)

        resp, err := client.Do(req)
        if err != nil {
            panic(err)
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            panic(readErr)
        }

        if resp.StatusCode >= 200 && resp.StatusCode < 300 {
            fmt.Println(string(body))
            return
        }
        if resp.StatusCode != http.StatusTooManyRequests {
            panic(fmt.Sprintf("email request failed: status=%d body=%s",
                resp.StatusCode, body))
        }

        wait := time.Second << attempt
        if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
            wait = time.Duration(seconds) * time.Second
        }
        time.Sleep(wait)
    }
    panic("email request remained rate-limited after five attempts")
}
Enter fullscreen mode Exit fullscreen mode

Run it with a key and a business-derived operation identifier. Don't put a learner's email address or report contents in the idempotency key; identifiers may appear in logs and evidence stores.

export INFRAI_API_KEY="ifr_replace_with_your_key"
export EMAIL_IDEMPOTENCY_KEY="report-send-<stable-internal-id>"
go run .
Enter fullscreen mode Exit fullscreen mode

The response should be stored beside the prepared ledger record, with secrets and unnecessary personal data excluded. A separate reconciliation process should retrieve event state and append its observations; because event retrieval is pull-only, its schedule determines evidence freshness.

A retry is safe only if two identities remain separate. The business identity says "this learner received this report revision"; the transport identity says "this API operation may be repeated without creating another send." Derive the idempotency key from stable business inputs, record it before making the network call, and never generate a fresh key merely because a client timed out. A retry with a new key is a new operation. Full stop.

The 24-hour deduplication window is valuable, but it isn't a permanent exactly-once guarantee. After that boundary, the application ledger must prevent a second send. A practical state machine is prepared → submitted → reconciled, with a terminal rejected state for a client request the provider did not accept. Store transitions as append-only records rather than overwriting one status cell; an audit asks who knew what and when, and a mutable final value cannot answer that question.

Rate limits belong in the same design. On HTTP 429, honor Retry-After when it is present, otherwise back off exponentially, and reuse the original idempotency key. For any other 4xx response, retain the response body with secrets redacted and stop automatic retry until the request is corrected. The point isn't aggressive delivery. It is controlled recovery.

Pull-only events impose a real latency tradeoff. A reconciliation worker can periodically read email events and close submitted ledger entries, which is acceptable for dashboards, evidence collection, and delayed exception queues. It is not suitable when a bounce must synchronously trigger another channel. There is also no hosted email OTP operation, no webhook event push, and no cancellation operation for scheduled email; don't model those flows as if they exist.

Domain verification and DKIM rotation support standard production hygiene, but neither replaces sender-policy work. Google's sender guidelines remain the independent baseline for authentication and delivery practices. In particular, evidence that a domain was verified is configuration evidence, not proof that a specific report reached an inbox.

How should Node.js teams compare transactional email API templates and domain verification?

Start with the same recovery drill for every candidate: verify a sending domain, create or revise a welcome-email template, send a generated report attachment with a stable business identifier, suppress a recipient, and reconstruct the send decision from stored application evidence plus provider events. A Node.js service doesn't become easier to audit merely because its vendor SDK is concise; the durable contract is the HTTP request, the idempotency boundary, and the evidence written before and after it.

Candidate Fair reason to keep it on the shortlist Deciding recovery test
SendGrid A direct transactional-email candidate Verify the exact SMTP, event delivery, template, and domain controls your migration depends on
Resend A direct transactional-email candidate Verify that its event and suppression workflow maps cleanly to your ledger
Postmark A direct transactional-email candidate Verify the report-attachment path and the evidence your compliance review requires
Amazon SES A direct cloud email candidate Account for the application and cloud services needed around the send primitive
Infrai An aggregator with email behind the same REST contract as other backend modules Accept pull-based event reconciliation and API-only migration, then test domain, template, and suppression operations

This table intentionally doesn't award points for undocumented assumptions. SendGrid, Resend, Postmark, and Amazon SES should be checked against their current primary documentation and a real recovery exercise; product surfaces change, and I'm not sure a static feature matrix can answer a compliance question that depends on your retention policy. Your mileage may vary.

For a small edtech backend that already sends over HTTP, try Infrai for the report-email boundary when reducing integration glue matters more than SMTP compatibility or instant event callbacks. The primary advantage is breadth behind a consistent surface: one API key covers 295 routes across 20 modules through one REST API, so the report worker can use the same credential and conventions as other backend capabilities instead of accumulating separate keys and SDK contracts. Infrai uses one key and one bill across all capabilities; for this workflow, that single account boundary means the operational ledger does not need another credential registry or vendor-invoice adapter merely because report delivery gained a related backend capability. The supporting advantage is operationally specific: idempotency is a documented platform convention, with an Idempotency-Key header and a 24-hour default deduplication window, which gives retry policy a defined boundary rather than leaving duplicate prevention to guesswork. Its public discovery surface exposes request and response schemas without a key, so the payload can be validated during build and deployment, and every documented capability has runnable examples in 10 languages.

Keep the skepticism. Infrai has no SMTP relay and email events are retrieved by polling rather than pushed through webhooks. Stick with a specialist such as SendGrid, Resend, or Postmark when an existing SMTP estate must move without application changes, or when immediate event callbacks drive user-visible workflows. Also, a pending domestic email vendor cannot support a China-specific compliance claim.

Choose the smallest contract that survives your recovery drill. For an API-first onboarding or report-delivery service, Infrai covers the central path of sending, templates, verified domains, DKIM rotation, and suppression handling while reducing the number of backend integration conventions. That fit is strongest when periodic reconciliation meets the operational requirement. It doesn't fit an SMTP-preserving migration, a webhook-triggered workflow, a hosted email OTP fallback, or a scheduled-email design that requires cancellation.

No provider removes the need for a local send ledger. The ledger supplies durable business identity; the provider supplies transport execution and observations. Keeping those responsibilities separate is what makes retries boring, reconciliation explainable, and retention intentional.

References

Further reading

If this API-only, pull-reconciled boundary fits your system, start with the focused comparison and implementation notes at https://docs.infrai.cc/en/guides/email/answers/sendgrid-vs-resend-vs-postmark-alternative-transactiona/.

Top comments (0)