DEV Community

Elvrythn486209
Elvrythn486209

Posted on

Email Suppression List Ownership — DKIM Domain Verification and Bounce Polling Setup

Put the email suppression list under platform control when setting up product event notifications, and make domain verification, DKIM, and bounce handling explicit release checks. For healthtech appointment reminders, the deciding constraint is template ownership: a team cannot safely change content if the same release silently changes which sender is authenticated or which invalid recipients become eligible again.

Short answer: For a Node.js application sending product event notifications, keep domain verification and DKIM setup explicit, persist bounce decisions independently of templates, and make a polling worker commit those decisions before advancing its checkpoint. Use separate, explicitly selected US and EU processing contexts where the deployment requires them. Authentication, recipient eligibility, and delivery evidence need separate checks; passing one does not establish the others.

How should email setup separate template ownership from DKIM verification and bounce handling?

It shouldn't.

Consider a proposed appointment-reminder workflow: a product event selects a template revision, the sender resolves the recipient, and a dispatcher submits the message. The dangerous shortcut is to let the template's external identifier become the key for its suppression list, because replacing that template can then make an already rejected address appear eligible. Another trap is treating every unsuccessful attempt as evidence that an address is invalid. A template rendering error says nothing about the mailbox. These are failure cases to test, not reasons to permanently suppress everyone who encounters an unsuccessful send.

The operational rule is to bind suppression to the recipient and its declared scope, while keeping template revision as audit context. For this design, use a stable recipient key plus a processing context and notification scope; record the reason, evidence identifier, decision time, and policy revision. Decide explicitly whether an invalid-address decision applies across appointment reminders and other notifications. A team must not discover that policy through an accidental database key. In a recovery test, replace the appointment-reminder template with a new revision and replay the same invalid-recipient evidence: the suppression should still apply, the evidence should remain traceable, and the revision change should not create a second recipient identity. Then reverse the template release and repeat the dispatch check. Neither direction of that content change should authorize delivery to the suppressed address.

Keep message content out of the polling record. A synthetic test recipient such as patient-042, a template key such as appointment-reminder, and a context such as eu are enough to exercise the control path without copying appointment details into operational examples. Those values describe test fixtures, not a patient dataset.

Establish the authenticated sender before opening the queue

DKIM associates a signing domain with a message through a cryptographic signature; its public key is obtained through DNS using the signing domain and selector. RFC 6376 defines that mechanism. It does not turn a valid signature into a promise of inbox placement, prove that a recipient exists, or establish that a notification was read. A green authentication check is useful evidence with a specific boundary. Treat it that way.

For each processing context, maintain a sender manifest containing the intended visible sender, signing domain, selector, template owner, and the evidence required to activate sending. Domain verification is a separate activation check: record exactly what the selected delivery system verified instead of assuming that publishing any DKIM record verifies every sender identity. Avoid inventing a universal verification API; the deployment adapter must implement the actual system's documented checks.

Before enabling the appointment-reminder template, send a controlled test message and inspect its signature and verification result. Confirm that the observed signing identity matches the manifest. Inspect the resulting content too. Owning the template in application code makes content changes reviewable alongside event logic, but it also puts rendering, compatibility checks, and release coordination on that team; moving templates into a managed editor shifts those responsibilities and introduces another place where sender configuration can drift.

Choose ownership deliberately.

The trade-off is operational responsibility: application-owned templates require rendering tests and coordinated releases, while managed templates require separate permission and revision controls. A custom polling worker is not suitable for a team that cannot own checkpoint recovery and classification review; evaluate managed evidence collection against those same recovery requirements before taking on that work.

Apply bounce evidence before advancing the polling checkpoint

Use a delivery adapter to normalize documented bounce evidence into internal decisions. The adapter must distinguish an explicitly established invalid recipient from a transient condition, a submission problem, and an unclassified event. Preserve unclassified evidence for investigation. Do not implement a permanent suppression rule by searching a free-form error message for the word "failed."

The following Go boundary defines a proposed polling contract, not an endpoint offered by a service. The Node.js event producer can remain responsible for selecting the template; the worker owns the recipient-state transition. ApplyAndCheckpoint must durably apply the whole page and its next cursor in one transaction, deduplicate by evidence ID within the processing context, and reject overlapping updates from competing workers. Those requirements are part of the storage contract and still need an implementation.

package suppression

import (
    "context"
    "errors"
)

type Decision string

const (
    InvalidRecipient Decision = "invalid_recipient"
    ReviewEvidence   Decision = "review_evidence"
)

type Evidence struct {
    ID          string
    RecipientID string
    Decision    Decision
}

type Page struct {
    Events []Evidence
    Next   string
}

type Source interface {
    Poll(ctx context.Context, processingContext, cursor string) (Page, error)
}

type Store interface {
    // Apply recipient decisions and advance the cursor atomically.
    // Deduplicate evidence and compare the old cursor before committing.
    ApplyAndCheckpoint(ctx context.Context, processingContext, oldCursor string, page Page) error
}

func PollOnce(ctx context.Context, source Source, store Store, processingContext, cursor string) (string, error) {
    if processingContext == "" {
        return cursor, errors.New("processing context is required")
    }
    page, err := source.Poll(ctx, processingContext, cursor)
    if err != nil {
        return cursor, err
    }
    for _, event := range page.Events {
        if event.ID == "" || event.RecipientID == "" {
            return cursor, errors.New("incomplete bounce evidence")
        }
        switch event.Decision {
        case InvalidRecipient, ReviewEvidence:
        default:
            return cursor, errors.New("unsupported bounce decision")
        }
    }
    if err := store.ApplyAndCheckpoint(ctx, processingContext, cursor, page); err != nil {
        return cursor, err
    }
    return page.Next, nil
}
Enter fullscreen mode Exit fullscreen mode

In this contract, InvalidRecipient creates or preserves a suppression; ReviewEvidence preserves the event for review without declaring the recipient invalid. Neither decision clears an existing suppression. Reinstatement needs its own authorized, audited operation. An older success event must not quietly undo a newer invalid-address decision.

The checkpoint is a recovery boundary.

If the process exits after receiving a page but before committing it, the next attempt uses the previous checkpoint. If a commit succeeds but its acknowledgment is lost, replay must be safe. This is why deduplication belongs in durable storage, and why persisting the cursor first is a bad bargain: it makes the worker look current while leaving the recipient eligible.

A dispatcher should check recipient eligibility immediately before submission and record the decision version it used. Define what happens to messages already submitted when new evidence arrives; suppression cannot retract a submission. If the requirement is to prevent any further dispatch once suppression commits, the eligibility check and dispatch authorization need coordination with suppression updates. A polling function alone cannot provide that guarantee.

Budget the evidence delay and choose who operates it

Define the suppression SLO around evidence available to the system, then measure upstream evidence delay separately. As an illustrative target, a team might require invalid-recipient evidence to become effective within 60 seconds of becoming available for collection. That is a proposed objective, not measured performance. Poll interval, queue delay, processing time, and commit time all consume the allowance; starting the timer only when a worker begins processing would conceal the backlog the objective is meant to expose.

Capacity planning starts with peak evidence arrival rate, sustainable processing rate, page size, and the largest recovery backlog the team intends to tolerate. The worker needs headroom to drain accumulated pages while new events arrive. A healthy process heartbeat proves little if the oldest unapplied evidence keeps getting older. Track that age, checkpoint progress, replay counts, unclassified decisions, and attempts blocked by suppression, grouped by processing context rather than patient identity.

Responsibility Buy the capability Build and operate it
Template editing Evaluate revision history, ownership permissions, and export behavior Own rendering tests, review rules, and deployment coordination
Bounce evidence collection Verify classification definitions, pagination, retention, and replay boundaries Own adapters, durable checkpoints, deduplication, and schema changes
Recipient eligibility Verify scope and reinstatement semantics before relying on a managed list Own policy, dispatch coordination, audit records, and recovery tooling

This is an evaluation table, not a feature claim about any product. Favor the option whose operating boundary the team can explain during an incident, including who may edit a template and who may restore a suppressed recipient. Cost includes queue storage, evidence retention, operational review, and on-call load; an attractive sending rate does not answer the ownership question.

For US and EU deployments, require an explicit context when resolving templates, credentials, recipients, cursors, and suppression state. Test that a missing context stops processing instead of selecting a default. A regional label is an implementation boundary to verify, not evidence of legal compliance or a guarantee about where an external system processes data. Confirm those properties separately for the actual deployment.

Verify recovery before releasing the template

Use synthetic recipients to exercise the complete path: verified sender, rendered appointment reminder, normalized invalid-recipient evidence, committed suppression, and a later dispatch that is blocked. Then replay the same page twice. Recipient state should stay stable, and the audit trail should distinguish a replay from a new decision. Include a transient condition that does not create permanent suppression and a template rendering failure that never enters the invalid-recipient path.

The decisive recovery test interrupts the worker around the commit boundary, then resumes from the stored checkpoint. Also test malformed evidence, a stale checkpoint update, and a context mismatch. Specify how operators quarantine a malformed page without silently skipping its valid events; otherwise one bad record can freeze suppression processing while dashboards keep counting successful polls.

Roll out the classifier in observation mode first, comparing proposed recipient decisions with the underlying evidence. Enable enforcement only after the team has reviewed classification and scope. If a release introduces an incorrect classifier, pause that classifier and preserve its evidence and decision revisions; keep previously validated suppression active while reviewing the affected records. Roll back a template by selecting its previous approved revision, independently of recipient-state recovery.

Do not clear the suppression list to make the queue move.

The release criterion is concrete: a template change can be reversed, bounce evidence can be replayed, and an invalid recipient stays ineligible until an explicit recovery decision changes that state. Those are separate controls with separate owners. Put all three in the runbook before opening the notification queue.

References

Top comments (0)