feat(app): send through the configured relay with TLS and authentication

- Read the relay password and CA file at startup; refuse to start on an unusable one
- Pass TLS mode, server name, CA pool, credentials and EHLO name to the SMTP relay
- Default the EHLO name to the host name
- Test an authenticating STARTTLS relay, a wrong password (mail stays queued) and the startup checks
- Document external relays in the README and the example config
This commit is contained in:
tgiachi 2026-11-10 11:05:24 +01:00
commit a6601caed7

View file

@ -140,6 +140,36 @@ Use `db: /data/parsimony.db` in the config. Do not publish the LMTP port (2424):
shared with the container, and `lmtp.allow` should list that network's range (see Security notes). A new named volume gets the right ownership by itself;
for a bind mount, make the host directory writable by uid 65532.
## Sending through an external relay
By default parsimony hands mail to an SMTP server on the same machine (`relay.addr: 127.0.0.1:25`). It can also send through
an external relay such as Amazon SES, Mailgun or a company smarthost:
```yaml
relay:
addr: email-smtp.eu-west-1.amazonaws.com:587
tls: starttls # none (default), starttls or tls (port 465)
username: AKIAEXAMPLE
password_file: /run/secrets/relay-password # the password is never in the config
helo: lists.example.org # EHLO name; this machine's host name by default
# ca_file: /etc/parsimony/private-ca.pem # to trust a private CA
# server_name: smtp.example.com # when the certificate is for another name than the host in addr
```
- **TLS is required, never silently skipped.** With `starttls` a relay that does not offer it makes the send fail; the
certificate is always verified (TLS 1.2 or later; system roots, or `ca_file`).
- **Credentials only travel encrypted.** SMTP AUTH PLAIN is refused over a clear connection to a remote relay, at load
time and again at send time. A local relay (127.0.0.1, `::1`, `localhost`) may be used without TLS.
- **A wrong password does not lose mail.** A refused login (or a relay that wants authentication) is treated as a temporary
error: the deliveries stay queued, retry with backoff, and show the reason in the queue (without the password). Fix the
password and restart; the mail goes out. A missing or empty password file, or an unreadable CA file, stops the daemon at
startup.
- With `starttls`, the very first EHLO before the upgrade says `localhost` (the SMTP library offers no way to set it
earlier); the configured `helo` is used right after, over TLS.
- Keep SPF and DKIM right for the path your mail takes (for SES, `include:amazonses.com` in SPF), and check that the provider
accepts the list's per-recipient return addresses (`list+bounce-ID-MAC@domain`) as envelope sender. Bounces come back
to those addresses, so they reach parsimony only if the domain's MX delivers them to its LMTP.
## Delivery and the queue
LMTP answers `250` when the post is in the queue, so a down relay never bounces mail back to Postfix.