Skip to content
How to install

Setup guide

Mail → Setup guide lists what delivery needs, in order, with your servers’ addresses filled in. Every check asks the domain’s own nameservers, so a record shows as done as soon as your DNS provider publishes it.

Mail → Setup guide with a server's hostname, reverse DNS and port 25 checks, and a domain's SPF, DKIM and DMARC steps
  • Access to the DNS of each sending domain, or a Cloudflare token that reaches its zone.
  • For direct delivery, access to the control panel where you rent each server.
  1. Servers: give each server’s mail hostname an A record. For direct delivery, also set the server’s reverse DNS to that name and get outbound port 25 opened.
  2. Sending domains: publish SPF, then DKIM, then DMARC, which acts on the other two.
  3. Prove it works: send a test message from the relay and from a site to a Gmail or Outlook address. Its headers should show DKIM-Signature, spf=pass and dkim=pass.

Each record names the DNS zone it goes in, and gives its name within that zone, the way DNS providers’ forms ask for it: _dmarc in example.com, and @ for the domain itself. Choose Check beside a record once you have added it, or Check all at the top. Reverse DNS is set where you rent the server, and Where did you rent this server? gives the steps for common providers.

WordPress sends a site’s mail from its primary domain, without www.: a site on www.example.com sends as [email protected]. A PHP site’s mail with no sender of its own goes out as [email protected]. So each site adds one sending domain.

  • A site’s other domains are not listed. They redirect to the primary, and no mail comes from them.
  • All dev addresses count as one sending domain, the dev domain, since a key there signs every site under it.
  • A domain with a DKIM key stays listed until you remove the key, even when no site sends from it.

With a DNS token, the guide writes the records instead of printing them: Publish on a domain, Publish A record on a mail hostname. It decides from the zone as it is at that moment, and reports what it did.

  • SPF is merged into a published record, never replaced.
  • Two SPF records, more than 10 DNS lookups, or a record that denies a server stop it. It says why.
  • A published DMARC record is never changed, even a broken one.
  • Other TXT records at the same name are kept.
  • DKIM is published only once its key is on every server.

Since 0.3.0-beta.2 Add a Cloudflare API token under Settings, then DNS, with Zone → Zone → Read and Zone → DNS → Edit. It is the same token the wildcard certificate and the site records use.

Reverse DNS has to match the hostname the relay announces. Each server has its own:

Server Default name
The panel’s server mail. and the panel’s domain without panel.: panel.example.com gives mail.example.com
A server added from the panel mail. and the dev domain, the same on every such server
  1. Under Servers, pick the server and choose Change hostname.
  2. Type a name you control and choose Apply. The relay reloads without losing queued mail.
  3. Point an A record for the name at the server, then change its reverse DNS to match.

Receivers treat a new name as a new sender.

Since 0.3.0-beta.2 The dialog shows the default, MAIL_HOSTNAME from deploy/.env. A name set in the panel wins over it and is kept when the relay restarts. Reset to default removes it, and so does typing the default name. From a shell, this sets a new default and clears a name set in the panel:

Terminal window
sudo /opt/wpl7/provision/setup.sh --mail-hostname=smtp.example.com
  • Reverse DNS and a smarthost’s SPF value are always set by hand.
  • Without a token, or for a zone it cannot reach, you add the records by hand. The panel publishes through Cloudflare only.
  • SPF is planned for the delivery mode of the panel’s own server, and checked for IPv4 only.