DEV Community

FrozenSigh2853916
FrozenSigh2853916

Posted on

Compliance Email Evidence — Five Node.js API Checks for Custom-Domain DKIM/SPF Before Send

#email #node #compliance

Send a compliance notice only after its identity, submission, and delivery evidence have separate records. Short answer: for a first transactional welcome email from a Node.js API, verify the custom domain, publish the sender's DKIM and SPF records, create an audit row before the API call, and treat delivery callbacks as evidence rather than as a synonym for sent.

The before/after model is simple. Before, the signup handler logs one line after calling a mail API. After, it creates a notice record, submits a versioned message with a stable identifier, and appends every observed state to that record. A reviewer can follow intent -> acceptance -> delivery -> bounce without guessing what a timestamp means.

That distinction is the whole job.

What should a Node.js API prove before its first welcome email?

Start with sender identity. DKIM adds a domain-linked signature that a receiving system can verify using the selector's public key; RFC 6376 also makes clear that a valid signature authenticates a signing domain, not the truth of the message or the character of its sender. SPF is another domain authorization check. Publish the exact records required by the system that sends your mail, and keep the envelope and visible From domains aligned with your policy.

Then define the evidence vocabulary. created means the application intended to send. accepted means the configured transport accepted a request. delivered means an authenticated callback reported transfer. opened is an observation about a client, not a receipt. Apple Mail Privacy Protection can download remote content and hide recipient activity, so an open signal cannot carry the same weight as a delivery event.

Create the audit row before the network call. Give it a locally generated noticeId, recipient, template revision, sender domain, creation time, and retention class. Store a content digest when retaining the full notice is inappropriate. A digest can later show that two byte sequences match; it cannot prove that a mailbox received either sequence.

One practical rule: never overwrite the previous state. Append events with their source, event ID, observed time, and raw event name. That makes a duplicate callback boring instead of mysterious.

How can a custom-domain DKIM/SPF setup support an auditable Node.js send?

Treat DNS as a deployment dependency, not a last-minute form field. Use a dedicated sending subdomain when organizational policy separates product mail from employee mail. Publish the DKIM selector and SPF record supplied by the actual transport, wait for verification, and send from an address under that verified domain. A green local test does not compensate for an unverified production identity.

The application boundary should stay boring and portable. The endpoint below is deliberately configured rather than named: providers use different paths and response shapes, and inventing a universal route would make a copy-paste example misleading.

type Submission = {
  messageId: string;
  state: "accepted";
};

type Notice = {
  noticeId: string;
  recipient: string;
  templateRevision: "welcome-compliance-v3";
};

function isSubmission(value: unknown): value is Submission {
  if (typeof value !== "object" || value === null) return false;
  const row = value as Record<string, unknown>;
  return typeof row.messageId === "string" && row.state === "accepted";
}

export async function submitWelcome(
  notice: Notice,
  signal?: AbortSignal,
): Promise<Submission> {
  const endpoint = process.env.DELIVERY_API_URL;
  const token = process.env.DELIVERY_API_TOKEN;
  if (!endpoint || !token) throw new Error("Missing delivery API configuration");

  const response = await fetch(endpoint, {
    method: "POST",
    signal,
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
      "idempotency-key": notice.noticeId,
    },
    body: JSON.stringify({
      from: "welcome@notices.example",
      to: notice.recipient,
      template: notice.templateRevision,
      metadata: { noticeId: notice.noticeId },
    }),
  });

  if (!response.ok) {
    throw new Error(`Submission rejected with status ${response.status}`);
  }
  const body: unknown = await response.json();
  if (!isSubmission(body)) throw new Error("Unexpected submission response");
  return body;
}
Enter fullscreen mode Exit fullscreen mode

The handler should persist noticeId before calling submitWelcome, then persist the returned messageId and accepted event in one transaction. If the process exits between those operations, a retry reuses the same idempotency key. The selected transport must document how repeated keys behave; the application should not assume that every API deduplicates forever.

Which delivery failures invalidate the evidence chain?

Most failures are bookkeeping failures disguised as email failures. A callback can arrive twice, arrive before a worker has loaded the notice, or carry an event name the application does not recognize. Authenticate the callback, validate its shape, deduplicate by event ID, and append unknown-but-well-formed observations for review instead of silently mapping them to delivered.

Test the awkward edges: duplicate submission, delayed callback, bounce, malformed callback, callback authentication failure, and a process exit after acceptance but before persistence. Assert on the audit history, not only on whether a message body was generated. In one useful test fixture, the same noticeId is submitted twice and produces one logical notice with two transport observations; that is far easier to explain during an audit than two rows called sent.

Logs answer “which notice changed?” Metrics answer “is the system drifting?” Alert on accepted messages that remain unresolved, callback lag, authentication failures, and a change in bounce rate. Keep message IDs and notice IDs correlated, but avoid putting full addresses or notice bodies into general-purpose logs.

Short logs. Long memory.

What are the trade-offs between hosted and self-operated mail?

A hosted transport can reduce the operational work around DNS verification, queues, reputation, abuse handling, and callback delivery. It also adds a processor, contract, retention policy, and external event schema to the evidence chain. A self-operated path gives the team more control over storage and routing, while making queue health, feedback loops, reputation, and diagnostics its responsibility. The right comparison axis is the evidence policy and the team's operating capacity, not the number of SDK methods.

This workflow is not suitable when a regulation requires acknowledged receipt, identity verification, or a mandated delivery channel. Stick with that channel and treat email as a convenience copy. It is also a poor fit for marketing campaigns, where consent, suppression, and preference management require a separate system of record.

I'm not sure a universal retention period exists. Legal obligations, privacy policy, and notice sensitivity decide it. Write that decision down, hash the rendered content when appropriate, and make the deletion boundary visible to reviewers.

A compact decision rule for the first send

Ship when five checks are green: the custom domain is verified; DKIM and SPF records match the sending system; the audit row exists before submission; callbacks are authenticated and idempotent; and tests cover the gap between acceptance and persistence. If any check is red, the honest state is “not ready,” not delivered.

The first welcome email is small, but its evidence model becomes a template for password resets, invoices, and account notices. Build the record once. Keep the vocabulary precise. Your future incident review will be shorter.

References

Top comments (0)