DEV Community

SunspireValerius59
SunspireValerius59

Posted on

Signup DKIM Failures — 3 Evidence Checks Before Retiring Logistics Email Templates

For logistics signup, keep one application-owned verification template and resolve DKIM failures before repeatedly sending its verification link. The operating bill includes send attempts, DNS administration, template maintenance, and retained diagnostic evidence. Start with evidence volume: in an illustrative capacity plan with 1,000 messages per day, a 24 KiB message retained for 7 days occupies 168,000 KiB; a 1 KiB diagnostic record for each message occupies 7,000 KiB. Raw messages dominate that example by a factor of 24. These are planning inputs, not measurements or service prices.

Short answer: separate DNS enrollment from message verification, inspect the actual signing domain and selector, then locate any changes after signing. Keep template rendering upstream of the signer. Reducing routine full-message retention moves the dominant storage term in the example, but only after a controlled test preserves enough evidence to distinguish lookup, body-hash, and signature failures.

The engineering question is who controls the bytes. A logistics account may need a verification link before it can finish signup; changing the subject, footer, or link after signing can create a different message from the one the signer authenticated. Template ownership therefore determines both the repair and the evidence worth retaining.

How do you diagnose DKIM verification failures when integrating email?

An integration screen reporting an unverified domain and a receiver reporting a failed DKIM signature are different observations. Record which one occurred before changing DNS. Enrollment is a service's provisioning check; DKIM message verification follows the signature carried by a particular message. A provisioning label alone cannot establish whether a delivered message passed DKIM.

Start with one controlled signup sent to a mailbox the team can inspect. Use a test account with no operational shipment data. Preserve its raw message temporarily, including the DKIM-Signature header and the receiving system's authentication result. RFC 6376 defines the signing and verification process; RFC 8601 defines Authentication-Results and explains why its trust boundary matters. Read the result added by the receiving system you trust, rather than treating every similarly named header as authoritative.

Keep the failures separate.

The first evidence check is the lookup identity. Read d= and s= from the actual DKIM-Signature. The public key lookup uses the selector under the signing domain: s._domainkey.d. For example, a test signature with d=signup.example and s=signup1 points to signup1._domainkey.signup.example. An address in From does not supply the selector. Neither does the template filename. If the integration expects an enrollment record elsewhere, document that separately rather than substituting it for the message's lookup. Inspect the effective TXT answer, accounting for any DNS indirection your integration requires. Compare it with the intended public key and record syntax. A TXT record can contain several character strings that form one value; several competing DKIM key records at the same name are a different problem. RFC 6376 describes key retrieval and record syntax.

Check the actual DNS answer before repeatedly pasting a key into a control panel.

SPF is separate. RFC 7208 evaluates whether an SMTP client is authorized for an envelope identity; a passing SPF result does not repair a DKIM signature. That distinction prevents irrelevant DNS editing.

Follow the signed bytes through the template boundary

The second check is the body hash. DKIM's bh= value authenticates the canonicalized body; its c= tag identifies canonicalization, with defaults defined in RFC 6376. A body-hash mismatch points the investigation toward differences between the signed body and the received body. Do not promise that relaxed canonicalization tolerates arbitrary edits. It handles specified whitespace transformations, not a substituted signup URL or a new HTML footer.

Map the path explicitly: application render, link generation, MIME assembly, signing, transport, and any subsequent rewriting. For an application-owned template, the application should finish its HTML and plain-text alternatives before the signing boundary. If another component owns the final template, establish where it renders and signs. Ownership of a template editor does not automatically mean ownership of the final MIME bytes.

This is where a logistics signup can become difficult to diagnose. A verification URL may be inserted during rendering, then rewritten for tracking elsewhere. Treat that sequence as a test case, not as evidence that rewriting is necessarily happening in your system. Compare a controlled message before signing with the received message, applying the signature's canonicalization rules.

The rendered preview isn't enough.

Looking only at what an email client displays misses changes in the underlying representation.

The third check is signature verification after lookup and body-hash checks. Inspect the key and algorithm, the signed header list in h=, and the signature's timing information when present. Header changes can invalidate a signature even when the body hash matches. Distinguish an unavailable DNS answer from a retrieved key that cannot validate the signature; their repairs and retry decisions differ. Use a DKIM verifier for the cryptography rather than implementing signature verification in a signup handler.

Alignment is another boundary. RFC 7489 describes how DKIM's signing domain can align with the visible From domain for DMARC. A cryptographically valid signature and a DMARC-aligned signature answer different questions. Preserve both results so a successful key repair doesn't conceal an identity mismatch.

Keep an evidence ledger that cannot replay a signup link

A useful routine record joins the signup send attempt to a template revision, a signer configuration revision, and the trusted receiver's result. It should explain which layer failed without becoming a second store of live verification links. Avoid recipient addresses, message bodies, tokens, and full URLs in ordinary diagnostic logs. A correlation identifier can still be sensitive when other systems can resolve it, so restrict access to the ledger too.

The following Python example defines a local evidence record. Its values are synthetic. It assumes that a separate verifier or trusted receiver has already produced the result; this code neither parses an untrusted header nor verifies DKIM.

from dataclasses import asdict, dataclass
import json


@dataclass(frozen=True)
class SignupEvidence:
    attempt_id: str
    template_revision: str
    signer_revision: str
    signing_domain: str
    selector: str
    dkim_result: str
    failure_stage: str


record = SignupEvidence(
    attempt_id="test-attempt-17",
    template_revision="logistics-signup-v3",
    signer_revision="signup-signer-v2",
    signing_domain="signup.example",
    selector="signup1",
    dkim_result="fail",
    failure_stage="body_hash",
)
print(json.dumps(asdict(record), sort_keys=True))
Enter fullscreen mode Exit fullscreen mode

Here, failure_stage is a local classification, not a standardized Authentication-Results field. Set it only when the available diagnostics support it. If a receiver reports only fail, retain that uncertainty rather than manufacturing a body-hash diagnosis.

Full-message captures remain useful during a bounded investigation. Restrict access, use controlled accounts where possible, and give captures an explicit deletion deadline. Redacting a signed body before verification changes the evidence. Verify within the restricted capture workflow first, then export only the diagnostic fields that routine operations need.

Deploy the repair without creating another delivery loop

Change the layer implicated by the evidence. Correct a selector or key publication problem in DNS; correct a post-signing body edit at the rendering or transport boundary. If template ownership is split, assign one owner to approve the final rendered message and identify which component signs it. A DNS edit cannot fix a footer added after signing.

For rollout, send a controlled message through the complete production path and inspect its received authentication results. Include the logistics signup template's HTML and plain-text forms, its verification link, and any localization variants actually deployed. A rendering preview does not exercise the signer or transport.

Test the real path.

DNS caching matters when validating a repair. Retain the queried name, observation time, and relevant TTL alongside the diagnostic evidence; an older cached answer can explain why observations differ. Avoid declaring success from one provisioning screen while messages still carry a different selector.

Track authentication outcomes by template revision and signer revision, along with send attempts and completed verifications. Keep these signals distinct: acceptance for delivery does not prove inbox placement, and a DKIM pass does not prove that a recipient completed signup. Pause automatic authentication-related retries until the underlying fault is understood. Otherwise the application can multiply attempts without changing the signed message or its verification outcome.

Retire the evidence deliberately

Once controlled messages validate the repair, stop keeping routine full MIME bodies and expired template renderings containing signup links. Keep the template source revision and the compact diagnostic ledger for a documented retention period tied to the investigation need. The 7-day window above is a capacity example, not a compliance requirement. Apply the obligations relevant to the actual signup data and jurisdiction.

The trade-off is concrete: after raw captures expire, the ledger can identify a failing revision or selector, but it cannot reconstruct an exact body mutation or recheck the original signature. A later failure may require a fresh controlled signup capture. Accept that diagnostic cost explicitly instead of silently accumulating a searchable archive of verification links.

Keep the template's final rendering before signing, retain enough evidence to locate the next failure, and give the rest a deletion date.

References

The specifications below support the distinctions between key retrieval, signed content, SPF, authentication results, and domain alignment. The capacity example and retention choices are engineering assumptions described in this note.

Further reading

Top comments (0)