Skip to content
Heatwave Docs

Postfix — host system-mail relay to SendGrid

How the bare-metal hosts relay system mail — cron output, pg-maintenance (VACUUM / pg_repack) reports, logwatch digests, ZED pool alerts, and root mail — out through SendGrid. This is not application mail: the Rails app sends directly to smtp.sendgrid.net; this relay carries only host/OS mail.

Provisioned automatically — don’t hand-configure it

Section titled “Provisioned automatically — don’t hand-configure it”

Postfix is set up by infra/terraform/files/provision-host.sh, applied at boot by cloud-init and re-applied idempotently by the heatwave-host-config Terraform workspace (the TFC agent SSHes in and re-runs the script). There is no manual satellite-relay wizard to click through — change the variable and re-run the host-config apply.

It installs postfix mailutils libsasl2-modules logwatch, configures postfix as a send-only satellite of [smtp.sendgrid.net]:587 (overridable via SMTP_RELAYHOST), and aliases root → sysadmin@warmlyyours.com.

What it configures

Section titled “What it configures”
Terminal window
# postconf -e … (set programmatically, not by editing main.cf by hand)
relayhost = [smtp.sendgrid.net]:587
smtp_tls_security_level = encrypt
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = static:apikey:<SendGrid send-only API key from 1Password>
smtp_sasl_security_options = noanonymous
smtp_sasl_tls_security_options = noanonymous
header_size_limit = 4096000

The API key is passed to provision-host.sh as SENDGRID_API_KEY (never committed); root mail routing is /etc/aliases → newaliases.

Critical gotcha — libsasl2-modules

Section titled “Critical gotcha — libsasl2-modules”

libsasl2-modules must be installed, or SMTP-client SASL auth to SendGrid fails with SASL authentication failure: No worthy mechs found and mail stays deferred in the queue. Minimal Ubuntu images omit it; the Chicago box (chi-latitude-heatwave-02) hit exactly this on 2026-06-07. provision-host.sh now installs it, but if you ever see deferred system mail, check this first:

Terminal window
apt-get install -y libsasl2-modules
systemctl restart postfix && postqueue -f

Verify

Section titled “Verify”
Terminal window
echo "test body" | mail -s "test subject" you@warmlyyours.com
postqueue -p          # empty = delivered; entries = deferred/failed

See also

Section titled “See also”