DKIM guide
When a recipient gets an email from updates@example.com, how can their mail server check that the domain signed it and the signed content survived delivery? The sender signs the finished message with a private key. The recipient uses the domain and selector in the signature to find the public key in DNS.
Choose a language for the eight code examples linked below. The DNS settings and lookup command are the same for every language.
Signing keys and DNS
Choose a selector for this key, such as mail2026, and a domain you control. For the examples, start with a 2048-bit RSA private key in dkim-private.pem. Keep that file on the signing system. The example below writes dkim-public.pem and prints the DNS record derived from the same key. DKIM RSA key sizes.
In the DNS zone for example.com, create one TXT record. Use the complete value printed by the example in place of the placeholder.
- Type
TXT- Name or host
mail2026._domainkeyif your provider appends the zone. The full record name ismail2026._domainkey.example.com.- Value
v=DKIM1; k=rsa; p=<base64 public key>
The p= field contains the public key as one continuous base64 value. Omit PEM headers and footers. Some DNS consoles display a long value as several quoted strings. That is valid when the strings belong to one TXT record and join without added spaces. DKIM TXT record format.
Query the full name and compare the returned p= value with the one the example printed.
nslookup -type=TXT mail2026._domainkey.example.com
When rotating keys, publish the new public key under a fresh selector. Check that it resolves before switching the signer. Leave the old record available while messages signed with the old key are still in transit.
Signing email
Finish the message first, including its From address, Date, Message-ID, attachments, and transfer encodings. For a saved message, load the complete .eml file into BinData. For a newly composed Email, use MailMan.RenderToMimeBd to get the bytes that will go over SMTP.
Set DkimDomain to example.com, DkimSelector to mail2026, and DkimAlg to rsa-sha256. Load the matching RSA private key with SetDkimPrivateKey. Include from in DkimHeaders and use DkimBodyLengthCount = 0 to sign the entire body. The relaxed setting for DkimCanon tolerates ordinary header folding and certain whitespace changes.
DkimSign adds a DKIM-Signature header to the same BinData. Write those bytes to signed.eml or pass them directly to SendMimeBd. A relay that adds a footer or rewrites links can invalidate the signature, so sign after the last such edit. For blind copies, put the additional addresses in the SMTP envelope.
Verifying email
Start with the original received MIME bytes, including attachments. Call NumDkimSigs to count the signatures and DkimVerify once for each zero-based index. Multiple signatures are common when both the sending domain and a mail service sign a message. Read VerifyInfo after each call, before the next result replaces it.
For a deployment check, use signed.eml from the signing example. First verify it against the saved public PEM. Then use a fresh Dkim object to call PrefetchPublicKey for the same selector and domain, and verify the same message again. If the saved key works but the DNS check fails, compare the record name and public key, and account for the resolver’s cache. A verifier with no matching cached key normally looks it up automatically.
- No signatures
- A count of zero means the received message has no DKIM signature to check.
- Signature verified
- The key for the signing domain verified the signed headers and body hash. Read
domaininVerifyInfoto see who signed. DMARC separately checks alignment with the visible From domain. - Verification failed
- A body-hash mismatch points to changed signed content, such as a footer added in transit. A missing key or DNS lookup failure can also prevent verification. Inspect
VerifyInfoandLastErrorTextfor the individual signature.