Skip to content
Hyperion

Set up SPF and DKIM for a site's mail

SPF tells receiving servers which machines may send mail for a domain. DKIM signs each message so a receiver can prove it was not forged. Both live in the DNS of the site’s domain, and Hyperion never edits DNS. It checks what is published, generates the DKIM key, and shows the exact records for you to publish at your DNS provider.

Both cards are on the hosting’s Emails tab, and every action runs on the node that serves the site, because the key and the mail leave from there.

Before you start

Section titled “Before you start”
  • You can edit the hosting’s configuration.
  • You can edit the domain’s DNS records at its provider.
  • The mail path of the node works. See Set up the outgoing mail relay.

Steps

Section titled “Steps”

Check SPF

Section titled “Check SPF”
  1. Open Hostings in the sidebar and click the site, then open the Emails tab.
  2. Find the Email DNS (SPF) card. It looks up the domain’s TXT records and the node’s public IPv4 address, and takes a few seconds.
  3. Read the pill:
Pill Meaning
authorized An existing SPF record authorizes the node’s IP through ip4:, a, mx, include: or a catch-all
not authorized An SPF record exists and does not list the node’s IP
missing No SPF record at the domain’s apex
multiple records Two or more SPF records. Receivers treat that as a permanent error and reject mail
could not check The lookup itself failed. This says nothing about your DNS
  1. For anything except authorized, read Suggested. The suggestion has the form v=spf1 ip4:<node IPv4> a mx ~all.
  2. At your DNS provider, add the suggested record as a TXT record on the apex of the domain. For not authorized, either replace the existing record with the suggestion, or add ip4:<node IPv4> to it before the trailing ~all. For multiple records, merge them into one by combining their mechanisms.
  3. Click Check again. The card shows when it last checked.

Enable DKIM

Section titled “Enable DKIM”
  1. On the same tab, find the DKIM signing card. Its pill reads off, or unavailable when OpenDKIM is not installed on the node.
  2. Click Enable DKIM.

The first time any domain on the node enables DKIM, Hyperion installs and configures OpenDKIM there. It then generates a 2048-bit RSA key for the domain with the selector hyperion, and turns on signing for mail whose sender address is on the hosting’s domain. Signing is live at once. Receivers only trust it after the DNS record is published.

  1. The card now shows three values. Add them at your DNS provider:
    • Host / name: hyperion._domainkey.<domain>
    • Type: TXT
    • Value: v=DKIM1; k=rsa; p=<public key>
  2. Wait for the record to propagate, then click Verify DNS.

The pill goes through publish DNS (enabled, not yet verified), verified, and key mismatch when a DKIM record exists at that name with a different key. Replace the record with the value on the card and verify again.

With DKIM on, Hyperion also changes the envelope sender of that site’s mail to its own domain. Receivers check SPF against the envelope sender, so the SPF record you published for the domain is the one they consult. A site with DKIM off keeps the node’s host name as envelope sender.

Turn DKIM off

Section titled “Turn DKIM off”
  1. Click Disable on the card. Mail from the site is no longer signed. The key stays on the node, and enabling DKIM again reuses it, so a record you already published stays valid.
  2. Remove the DNS record at your provider when you no longer need it.

From the command line

Section titled “From the command line”

On the node:

Terminal window
sudo hctl dkim status example.com
sudo hctl dkim enable example.com
sudo hctl dkim verify example.com
sudo hctl dkim disable example.com
sudo hctl dns spf example.com

dkim enable prints the TXT record to publish. dkim verify tells you when the published record matches the key.

Check that it worked

Section titled “Check that it worked”
  • Email DNS (SPF) reads authorized.
  • DKIM signing reads verified, and the card says “Published record matches — <domain>’s mail is DKIM-signed and verifiable.”
  • Query DNS yourself:
Terminal window
dig +short TXT hyperion._domainkey.example.com

Expected: a record starting with "v=DKIM1; k=rsa; p=".

  • Send a message from the site to a mailbox you control and read its headers. The Authentication-Results header should list dkim=pass and spf=pass.

If it fails

Section titled “If it fails”
  • “No matching record found yet. DNS can take a while to propagate — add it and Verify again.”: the record is not visible yet. Wait and click Verify DNS again.
  • “A DKIM record exists at that name but its key differs from ours — replace it with the value above, then Verify.”: an old record is published. Replace its value.
  • The lookup itself failed on this node: the card says this says nothing about your record. The usual causes are dig missing on the node, or DNS unreachable from it. Fix that, then verify again.
  • Enable DKIM shows an error under the card title: the node could not install or configure OpenDKIM, or write the key. Nothing is left half enabled: Hyperion removes partial signing entries before it reports the error.
  • “cannot enable DKIM on a deleting hosting”: the hosting is being deleted.