TL;DR: Treat every contact-form notification as an auditable state machine, not a successful API call. Verify a DKIM-aligned sending domain, consult a regional suppression set before enqueueing, assign an idempotency key, and poll the delivery interface until each attempt reaches a terminal state. For a healthtech support router, that evidence is what separates "accepted" from "handled."
The storage bill is driven less by the contact form itself than by retained delivery evidence: status snapshots, response metadata, retry records, and suppression history. Model it before choosing a retention period. If E is daily events, P is polls per event, B is bytes per observation, and D is retained days, the dominant term is approximately E × P × B × D; reducing redundant snapshots moves that term without weakening the final audit record.
1. What should a Node.js email deliverability setup record for each product event?
A support-routing event needs two identities: a stable business event ID and a distinct delivery-attempt ID. The first prevents a repeated form submission or worker replay from creating another logical notification; the second preserves every actual send attempt, including one that was accepted and later bounced. Exactly-once delivery cannot be inferred from an HTTP success response, so the defensible target is exactly-once state transition for the business event, with at-least-once workers and idempotent writes around it.
Persist a compact transition ledger: event ID, routing decision, destination class, region, content-template revision, attempt ID, provider-neutral status, observed timestamp, and a digest of the provider response. Do not put the patient's free-text message into that ledger. Keeping operational evidence separate from message content narrows the sensitive-data footprint and makes deletion policy easier to enforce.
Less data, on purpose.
Suppose one logical notification is polled six times. Keeping six complete payload copies multiplies the dominant storage term; keeping five small transition deltas plus one terminal record preserves the useful chronology. The deliberate loss is the full intermediate response body. During an unusual dispute, that means less forensic detail, which is an explicit retention trade-off rather than an accidental gap.
2. Authenticate the domain before trusting the route
DKIM signs selected message headers and the body with a domain-associated private key; a receiver retrieves the public key from DNS and verifies the signature. RFC 6376 also makes an important boundary clear: a valid signature establishes responsibility by the signing domain, but it does not by itself assert that the signer is trustworthy.
Use a dedicated sending subdomain for health-support notifications, publish the selector record, and verify it from outside the deployment network before enabling production traffic. Record the selector and configuration revision with the deployment evidence, but never store the private key in the event ledger. Rotation should overlap old and new selectors long enough for already-sent mail to remain verifiable under the operational policy you have chosen. The precise overlap is a policy decision, not a universal number supplied by DKIM.
This check is binary at release time: the expected public key is resolvable and a test message verifies, or sending remains disabled. A dashboard that merely says "domain verified" is weaker evidence than a repeatable DNS and message-verification test.
3. Make suppression a transactional decision
A suppression list is part of routing correctness. Consult it in the same transaction that claims the outbox event, or attach a versioned suppression decision to that event before any worker can send. Otherwise, a bounce consumer and a delivery worker can race: the consumer suppresses an address while the worker acts on an earlier read.
The suppression record should contain a normalized destination key, reason category, source attempt, first-observed time, latest-observed time, and review state. Hashing can reduce casual exposure, but a plain unsalted hash of an email address is guessable; use a keyed digest when the system only needs equality checks. Keep the key outside the database.
Hard failure and policy suppression belong in terminal states. A transient delivery condition may be retried under a bounded schedule, while an unknown status remains pending and must not silently become delivered. This distinction matters for a contact form: an agent queue should not show "notified" until the evidence supports that state.
| Internal state | Worker action | Audit consequence |
|---|---|---|
| Pending | Poll again under the bounded schedule | Preserve the last observation |
| Delivered | Stop retrying | Seal the terminal transition |
| Bounced | Suppress according to policy | Link the reason to the source attempt |
| Suppressed | Do not enqueue | Record the suppression decision |
4. Poll with monotonic, idempotent state transitions
Polling is useful when callbacks cannot cross a regional boundary or when the team needs an independent reconciliation path. The interface can stay generic: list attempts updated after a cursor, translate external states into a small internal vocabulary, and apply only monotonic transitions.
package delivery
import (
"context"
"errors"
"time"
)
type Status string
const (
Pending Status = "pending"
Accepted Status = "accepted"
Delivered Status = "delivered"
Suppressed Status = "suppressed"
Bounced Status = "bounced"
)
type Observation struct {
AttemptID string
Status Status
Observed time.Time
Cursor string
}
type Source interface {
Poll(context.Context, string) ([]Observation, string, error)
}
type Ledger interface {
ApplyIfNewer(context.Context, Observation) error
CommitCursor(context.Context, string) error
}
func Reconcile(ctx context.Context, src Source, db Ledger, cursor string) error {
observations, next, err := src.Poll(ctx, cursor)
if err != nil {
return err
}
for _, observation := range observations {
if observation.AttemptID == "" || observation.Observed.IsZero() {
return errors.New("invalid delivery observation")
}
if err := db.ApplyIfNewer(ctx, observation); err != nil {
return err
}
}
return db.CommitCursor(ctx, next)
}
ApplyIfNewer needs a uniqueness constraint on the attempt and observation identity, plus a transition table that rejects regressions such as delivered to pending. Commit the cursor only after every observation is durable. If the process dies before that commit, the page is read again and the uniqueness rule absorbs duplicates.
No guesswork.
A separate reconciliation job should revisit nonterminal attempts by age bucket. Alert on the oldest pending attempt and on queue-level gaps, not merely on worker exceptions; a perfectly healthy poller can repeatedly receive an incomplete page. Test duplicate pages, reordered observations, an unchanged cursor, a cursor that advances over an invalid record, and cancellation midway through a batch.
5. Keep US and EU evidence planes separate
Regional delivery reliability starts with an explicit data map. Route the contact form to the correct support queue using a recorded rule, then keep message content, delivery metadata, suppression entries, and operator access within the intended regional plane. A global control plane may coordinate configuration only if its data fields and access paths satisfy the organization's approved compliance design. This article cannot supply that approval; applicable obligations depend on the data, controllers, processors, contracts, and jurisdictions involved.
Deploy the same state machine and test suite in both regions. Let endpoints, credentials, keys, queues, and retention policies vary by configuration, and prevent one region from becoming the silent failover destination for the other. Disaster recovery deserves the same scrutiny: a backup copied across a boundary is still a copy.
SMS can use the same event and attempt ledger, but its authentication and handset behavior differ from email. Apple's Password AutoFill documentation describes domain-bound one-time-code conventions; that is relevant to authentication codes, not proof that a health-support notification was delivered. Do not collapse channel-specific evidence into a single "sent" Boolean.
The final release gate is concise: domain verification passes externally, suppression races are covered by a transactional test, repeated poll pages do not duplicate transitions, terminal bounces prevent later sends, regional configuration cannot cross-connect, and the audit export reconstructs one event without exposing its message body. Retain terminal facts and suppression provenance for the approved period; discard redundant snapshots and sensitive content as soon as policy permits. When something goes wrong, the cost is reduced intermediate forensics, accepted in exchange for a smaller and more defensible data footprint.
Top comments (0)