Skip to content
MailDock Docs

Rotate a domain's DKIM key

When to use: yearly as hygiene, after a suspected compromise of the server or a backup, when a receiver reports a DKIM key that is too weak/old, or when a dkim_unreadable alert names the domain because SECRET_ENCRYPTION_KEY was lost — rotating gives it a key sealed under the current one, and the alert resolves on that apply (DKIM signing). Preconditions: you can edit the domain’s DNS; the domain currently verifies (Domains → → DNS & routing shows the active _domainkey record verified).

Steps

Section titled “Steps”
  1. Domains → → DKIM keys → Rotate key (or POST /api/v1/domains/{id}/dkim). A new selector (ms<yyyymm>) is active immediately; the old one shows as retired with its date. Rspamd signs the next message with the new key.
  2. Publish the new TXT record shown in the domain’s DNS & routing section (<new-selector>._domainkey.<domain>); leave the retired selector’s record in place.
  3. Verify now until the new record is verified (it is propagating while resolvers catch up). Mail sent in the meantime is signed with the new key and only verifies where the new record is already visible — rotate at a quiet time, or publish the record a few minutes before rotating if you prefer (rotation is instant; DNS is not).
  4. After 30 days (the retired row shows the date it was retired; the 30 days is in its hint): delete the retired key (Delete on the retired row, or DELETE /api/v1/domains/{id}/dkim/{selector}), then remove its TXT record from DNS.

Verification

Section titled “Verification”

Send a message from a mailbox in the domain to an external account and inspect the headers: DKIM-Signature: … d=<domain>; s=<new-selector> and Authentication-Results: … dkim=pass. GET /api/v1/domains/{id}/dkim lists the new key as active; the configuration history (Settings → History) has a new version whose message starts with dkim: rotated.

Rollback

Section titled “Rollback”

There is no “un-rotate”: if the new record cannot be published, rotate again once DNS is fixed — each rotation is a fresh key. Mail signed with the old key keeps verifying as long as its record is published. Restoring a database backup taken before the rotation also restores the old key set (the next apply pushes it to rspamd) — the DNS records must then match that older set.