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

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

# 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

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:

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

Verify

echo "test body" | mail -s "test subject" you@warmlyyours.com
postqueue -p          # empty = delivered; entries = deferred/failed

See also