Diagnose mail delivery on a node

Every site’s PHP mail() hands its message to /usr/sbin/sendmail, which is postfix on the node. The Mail delivery group on Service health checks that path: how postfix sends, whether the server’s identity is acceptable to receivers, whether outbound ports are open and what is stuck in the queue. Use it when mail does not arrive.

Before you start

• You are an Administrator or an Owner.
• You know which node serves the site whose mail fails. The checks run on one node at a time.
• For relay settings, see Set up the outgoing mail relay.

Steps

1. Open Service health in the sidebar, under Operations. With worker nodes, click the node’s row. A single server opens straight to its page.
2. Click Mail delivery at the top of the page, or scroll to the group headed “Mail delivery · <node>”. The checks load when the group scrolls into view, because they run DNS lookups and port probes. Click Re-check to run them again. A DNS change can take a few minutes to show.
3. Read each row. A dot colours it green, orange or red. A row with no colour could not run, which is not a finding.

Row	What it tells you	Typical fix
Postfix	Mode (relays through a smart host, delivers directly, or default configuration), running or stopped, start at boot, sendmail present	Click Reconfigure postfix for “Default configuration”. Install postfix from its row under “Not installed on this node” when it is missing
Hostname (HELO)	The name postfix introduces itself with. Most receivers refuse a HELO without a dotted name	sudo hostnamectl set-hostname <name>.<domain>, then Reconfigure postfix
Reverse DNS (PTR)	Whether the node’s public IPv4 has a PTR record that matches the HELO name	Set the PTR where the address is managed, for example at the server provider. Hyperion cannot change it. A missing PTR is the most common reason direct delivery is refused before SPF or DKIM are looked at
Sender identity	Whether the sender address’s domain has an SPF record that authorizes this server	Publish the suggested TXT record, or change the sender address on Settings, Mail to a domain you control. A domain that makes receivers silently discard the mail shows in red
Outbound ports	Whether ports to SMTP servers are open. Open Each port for latency per port	If port 25 is blocked and the node delivers directly, turn on a relay that accepts submission on an open port, or ask the provider to unblock outbound TCP 25
Queue	Deferred messages	See below

4. Below the rows, the Mail log fold shows the last lines of /var/log/mail.log. It opens by itself when the queue holds messages.

Retry or discard the queue

When the Queue row shows deferred messages, it lists them with postqueue -p. The usual cause is blocked outbound port 25. Other causes are a PTR mismatch, a recipient refusing on SPF, or a recipient’s server timing out. The mail log says which.

1. Fix the cause first.
2. Click Retry now. It runs postqueue -f and answers “Queue retried — it is empty now.” or “Queue retried — N message(s) still deferred; the mail log says why.”

Before you discard the queue

Discard queue runs postsuper -d ALL and removes every queued message on this node, including genuine mail not yet delivered. A queue full of spam from a compromised site is the usual reason: clean the site first.

There is no backup of a mail queue. Open the Queue listing fold and read the recipients to confirm none of the messages is worth keeping. This cannot be undone.

3. Click Discard queue and confirm “Discard all”. The page answers “N queued message(s) discarded.”

Test the path a site’s mail takes

1. In Test via local sendmail, enter an address and click Send test.
2. The test hands one message to /usr/sbin/sendmail, exactly as mail() does. “Postfix queued the message to <address>.” means postfix accepted it. Delivery shows in the mail log a few seconds later. Test sends are limited to 3 per minute from one client address.

The test on Settings, Mail talks to the relay directly and skips postfix. The test here goes through postfix. On the command line the same checks are sudo hctl mail test <address>, sudo hctl mail status, sudo hctl mail flush and sudo hctl mail clear.

Reconfigure postfix

Reconfigure postfix re-applies what the agent applies when it starts: smart host when the node’s relay is on, direct delivery when it is off. It does not restart anything. Use it after you edit agent.toml by hand or fix the host name. The page answers “Postfix reconfigured — now in <mode> mode.”

Check that it worked

• Postfix is green and reads “Relays through <relay host> · running” or “Delivers directly to each recipient’s server · running”.
• Queue reads “Empty”.
• The test arrives, and its delivery line appears in the Mail log fold.
• The Local mail server card on Settings, Mail shows the same mode on one line.

If it fails

• “Postfix is not installed — install it first.” (after Reconfigure postfix): install postfix from the Not installed on this node fold on the same page.
• “admin role required”, “admin role required to reconfigure postfix” or “admin role required to send test e-mail”: your user lacks the Settings permission.
• “sendmail exit N: …”: postfix refused the test message. The text after the colon is the first 180 characters of sendmail’s output.
• “Test e-mail rate limit exceeded — wait a minute.”: wait 60 seconds.
• “Could not read the mail server on <node>: …”: the node’s agent did not answer. Click Try again, and check the node on Service health.
• One site’s mail never shows on this node: a site that sends over SMTP through a plugin bypasses this path. Its Emails tab shows “No outbound mail captured yet” under Mail sent by this site, and nothing is broken.