Set up the outgoing mail relay

Every node sends email on its own: the panel’s alerts and customer letters, and the mail() calls of the sites it hosts. With an SMTP relay configured and switched on, all of it goes through the relay. With the relay off, the panel sends no email to administrators or customers, and postfix delivers site mail straight to each recipient’s server. Mail sent straight from a server to public mailboxes is often filtered as spam, so a relay is the usual choice.

You configure it on Settings, Mail.

Before you start

• You are an Owner to change anything. An Administrator can see the relay and send a test message.
• You have the relay’s host, port, encryption mode and credentials. Postmark, Mailgun, SendGrid, Brevo, Amazon SES and Gmail SMTP are all usable, as is a postfix of your own that relays outbound.
• You have a sender address on a domain you control, whose SPF record lists the relay. A placeholder on somebody else’s domain is accepted by the relay and then silently discarded by the receiver.

Steps

1. Open Settings in the sidebar, then Mail under Basics.
2. With worker nodes enrolled, choose the node in the Node list (“This server (master)” or a worker) and click Show. Every card on the page follows that choice, and each node has its own relay.
3. In Outgoing relay, tick Send through this relay.
4. Fill in the form, or on the master click Detect a local relay first. It checks localhost ports 25 and 587 for a postfix or exim that already accepts mail and fills the form. The sender address it suggests comes from /etc/mailname. Nothing is saved until you click Save.

Field	What to enter
Relay host	The relay’s host name, for example smtp.example.com
Port	1 to 65535. The form shows 587 when none is set
Encryption	STARTTLS, TLS or None
Username	The relay account
Password	The relay password. When one is stored the label reads “stored — leave blank to keep”
Sender name	Defaults to “Hyperion” in the form
Sender address	The From address, on a domain whose SPF lists the relay

5. Click Save. The agent on that node restarts in about 5 seconds.

The addresses that receive alerts are edited elsewhere. See Set up alert channels. The Save here does not touch them.

Send a test message

1. Find the Test message card. It is available only while the relay is on.
2. Enter an address in Send to. It starts with the node’s first administrator address.
3. Click Send test.

The result shows the relay’s answer. A 250 means the relay accepted the message. Test sends are limited to 3 per minute from one client address, and the recipient address must be at most 254 characters.

Raise the largest message

When a site’s mail() fails with “message file too big”, usually a contact form with an attachment, postfix refused the message.

1. In Largest message, enter Limit in MB. 0 leaves postfix’s own limit (10 MB unless changed by hand). The form accepts up to 100.
2. Click Save.

Hyperion applies the limit at once and on every agent start. The limit counts the encoded message, so attachments get about three quarters of it. Most receivers, and most relays, take up to 25 MB. Above that, the refusal only moves to them as a bounce. Setting 0 later does not undo a raised limit. Enter 10 to return to about postfix’s default.

Read the local mail server line

The Local mail server card shows one line about postfix on this node, for example “Postfix relays through the smart host · running · queue empty.” The three modes read “Postfix relays through the smart host” (relay on), “Postfix delivers directly” (relay off) and “Postfix runs its default configuration” (Hyperion has not configured it yet). The line turns orange when the queue holds messages or postfix is on its default configuration, and red when postfix is stopped or sendmail is missing. Click Details and fixes on Service health for the full diagnosis, described in Diagnose mail delivery on a node.

Check that it worked

• The Outgoing relay pill reads relay on.
• Send test reports a relay answer starting with 250, and the message arrives in the inbox or spam folder.
• The test appears in the Email log with state Sent. See Find out whether an email was delivered.
• On the node, send a message through the same path a site’s mail() takes:

sudo hctl mail test you@example.com
sudo hctl mail status

hctl mail status shows postfix mode, relay, queue and recent log lines.

If it fails

• “The agent did not answer (…), so its relay is not shown.”: the page offers no form, because saving a form filled with defaults would overwrite the real values. Click Try again.
• “admin role required to send test emails”: your user lacks the Settings permission.
• “test email rate limit exceeded — wait a minute”: wait 60 seconds.
• The test result shows a refusal from the relay: the Email log row holds the relay’s full reply. Check host, port, encryption and credentials, and the sender address.
• The test is accepted and nothing arrives: check the sender address’s domain has an SPF record that lists the relay, and look in the spam folder. Sender identity on Service health reports an unsuitable sender.
• Alerts never arrive although the relay is on: the node has no addresses under Recipients. See Set up alert channels.

Related

• Run the setup wizard