DKIM Signing

DKIM (DomainKeys Identified Mail) is an email authentication standard that uses cryptographic signatures to prove that an outgoing message was authorized by the domain it claims to come from. Setting up DKIM dramatically improves deliverability and reduces the chance of legitimate mail being marked as spam by recipient servers.

How DKIM Works#

Opterius Mail / Postfix sends a message
         ↓
Signing agent (Rspamd or OpenDKIM) adds a DKIM-Signature header
using the private key stored on the server
         ↓
Recipient's mail server looks up the public key in DNS
(mail._domainkey.example.com TXT record)
         ↓
Recipient verifies the signature matches the message content
         ↓
Pass: message marked as DKIM-authenticated
Fail: message may be rejected or marked as spam

The private key lives only on your server. The public key is published in DNS so the world can verify signatures. There is no secret shared with anyone — the asymmetry is what makes this secure.

Generating a DKIM Key#

1. Go to Admin → DKIM.
2. Select the domain from the dropdown (e.g., example.com).
3. Click Generate Key.

Opterius Mail's DkimService generates a 2048-bit RSA key pair:

• The private key is stored securely on the server (path configured in config/mail-ui.php, typically /etc/opendkim/keys/{domain}/mail.private).
• The public key is displayed on screen as a formatted DNS TXT record ready to copy.

The key selector is mail by default, which means the DNS record name is mail._domainkey.{domain}.

Adding the DNS Record#

After generating the key, copy the displayed DNS record and add it to your domain's DNS configuration at your registrar or DNS provider.

The record looks like this:

Name:   mail._domainkey.example.com
Type:   TXT
TTL:    3600
Value:  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

Important formatting notes:

• The p= value is a base64-encoded public key. It may be split across multiple strings in the DNS interface (some providers require this for long TXT records). Each chunk must be a separate quoted string.
• Do not include v=DKIM1; k=rsa; p= without the surrounding quotes — the entire value must be one or more quoted strings.
• If your DNS provider shows a single text field, paste the full value including the quotes exactly as shown in the admin panel.

Example for Common DNS Providers#

Cloudflare: Enter mail._domainkey as the name (Cloudflare appends the domain automatically). Paste the full quoted value in the Content field.

cPanel/WHM: Go to Zone Editor → Add Record → TXT. Name: mail._domainkey.example.com. (note the trailing dot). Content: the quoted value.

Route 53: Create a TXT record. Name: mail._domainkey.example.com. Value: paste the quoted string.

Verifying the DNS Record#

After adding the DNS record, return to Admin → DKIM and click Verify DNS. Opterius Mail performs a live TXT lookup for mail._domainkey.{domain} and checks that the public key in DNS matches the private key stored on the server.

Status indicators:

DNS propagation typically takes 5–60 minutes. If verification fails immediately after adding the record, wait a few minutes and try again.

OpenDKIM Integration#

Opterius Mail generates the key and DNS record. The actual signing of outgoing messages is handled by OpenDKIM (or Rspamd's DKIM signing module if you are using Rspamd).

When using OpenDKIM, the Opterius Panel installer configures the relevant paths. The private key is written to:

/etc/opendkim/keys/{domain}/mail.private

OpenDKIM's KeyTable entry:

mail._domainkey.example.com  example.com:mail:/etc/opendkim/keys/example.com/mail.private

OpenDKIM's SigningTable entry:

*@example.com  mail._domainkey.example.com

After generating a new key in the Opterius Mail admin panel, reload OpenDKIM to apply it:

sudo systemctl reload opendkim

Rotating a DKIM Key#

To rotate a key (recommended periodically or after a suspected compromise):

1. Go to Admin → DKIM → [domain] → Rotate Key.
2. A new key pair is generated.
3. Add the new DNS record alongside the old one (use a different selector, e.g. mail2._domainkey).
4. Once the new DNS record has propagated and verified, update the signing configuration to use the new selector.
5. Remove the old DNS record after a few days (give remote servers time to verify in-flight mail signed with the old key).

The admin panel currently uses the mail selector by default. For multi-selector setups, the key file path must be updated manually in the OpenDKIM configuration.

Checking DKIM From the Command Line#

# Look up the DNS record directly
dig TXT mail._domainkey.example.com +short

# Check with nslookup
nslookup -type=TXT mail._domainkey.example.com