# Infrastructure design - U1 mail-foundation ## Configuration keys (per environment, on the host) | Key | Where | Example / note | |---|---|---| | `Email__Smtp__Host` | `shared/env` | `mail.slpsoftware.nl` (the SMTP host SimpleDeckApp uses in production, per Bryan). Setting it switches mail ON. | | `Email__Smtp__Port` | `shared/env` | `587` | | `Email__Smtp__EnableSsl` | `shared/env` | `true` (STARTTLS) | | `Email__Smtp__Username`, `Email__Smtp__Password` | `shared/env` (mode 600) | secrets, never committed, never in messages or logs | | `App__PublicBaseUrl` | `shared/env` | `https://test.andreaslop.nl` (https, no path) | | `App__DefaultLanguage` | optional | `nl` (default) or `en` | | `Email__FromAddress`, `Email__FromName` | committed default or env | `no-reply@slpsoftware.nl` / site name (SimpleDeckApp's committed default) | | `Email__AllowedFromAddresses__0..n` | env | extra sender addresses a site may choose in its settings; empty = only `FromAddress` | | `Email__LogoUrl`, `Email__BrandColor` | committed (ASF) or env | `/admin/brand-logo-on-light.png`, `#5f6a58` | Start-up validation refuses a broken mail configuration (when a host is set) with a message that never contains the credentials. Without a host nothing changes. ## Local development smtp4dev (already installed) on `localhost:25`: `Email__Smtp__Host=localhost`, `Email__Smtp__Port=25`, `Email__Smtp__EnableSsl=false`, no username, `App__PublicBaseUrl=http://localhost:5200` (http is accepted for loopback only). ## ASF test host (Operations will do it, needs Bryan's go for the real test mail) 1. Add the keys above to `shared/env` of `andreaslopfotografie-test` (mode 600 stays), restart the unit. 2. `Email__FromAddress` stays `no-reply@slpsoftware.nl` (the SMTP service's own domain). A sender on `@andreaslop.nl` only after the check below. 3. One real test mail to an address of Bryan before approval. ## Sender-domain alignment (production checklist item) `From:` domain, SPF and DKIM must agree with the SMTP service that actually sends: - SPF of the `From:` domain must authorise the sending service (today both `slpsoftware.nl` and `andreaslop.nl` publish `v=spf1 a mx include:smtp.spf.ziggo.nl ~all`). - That service must DKIM-sign for the `From:` domain (a `dkim._domainkey` record exists for both domains; whether the service signs with it is not visible from outside). - `mail.slpsoftware.nl` will deliver `@andreaslop.nl` mail properly only if it may send/sign for that domain. DMARC is `p=none` today (monitoring only). - Therefore the sender list is an allowlist: add an `@andreaslop.nl` address to `Email__AllowedFromAddresses` only after this is confirmed. ## No other infrastructure No new service, port, queue or storage. One additive table (`SiteSettings`) in the existing database. ## Per-host SMTP server (update 2026-11-08, from Bryan via "CMS & API") The SMTP settings are per host (all in that host's `shared/env`), so each site can use its own mail server: | Site | SMTP host | Sender domain | Status | |---|---|---|---| | SlpSoftware | `mail.slpsoftware.nl` (the host SimpleDeckApp uses) | `@slpsoftware.nl` | as before | | ASF (test, later production) | probably `mail.andreaslop.nl` (not `mail.slpsoftware.nl`) | `@andreaslop.nl` | **to be confirmed** | Read-only checks done from the developer PC (by "CMS & API"): `mail.andreaslop.nl` and `andreaslop.nl` both resolve to 217.121.250.215; the MX of `andreaslop.nl` is `mail.andreaslop.nl` (preference 10); TCP 587 is reachable. This fits the published SPF (`a mx`): a mail sent by that server for `@andreaslop.nl` is SPF-aligned, which the earlier plan (`mail.slpsoftware.nl` for ASF) would not have been. **Open points (Operations plan, no code needed):** 1. Which mailbox/account on `mail.andreaslop.nl` is used, and whether it may send with `no-reply@andreaslop.nl` (or another address) as `From`. Then ASF sets `Email__FromAddress` and `Email__AllowedFromAddresses__n` accordingly (the committed ASF default `no-reply@slpsoftware.nl` is only a placeholder until then). SlpSoftware keeps `mail.slpsoftware.nl`. 2. Port and TLS: not yet confirmed that the server offers STARTTLS on 587 (`Email__Smtp__EnableSsl=true`); if it needs implicit TLS (465) or none, the sender must be adapted (it supports STARTTLS or plain today) and a plain connection would not be acceptable beyond a private network. 3. DKIM: a `dkim._domainkey.andreaslop.nl` record exists; confirm the server signs with that key. DMARC is `p=none` (monitoring only). 4. Credentials for that account go into the ASF test unit's `shared/env` by whoever manages the host (not by this feature's code or by chat). ## Release notes for the host manager (required environment variables per release) - **This release adds NO required environment variable.** A host without any mail setting starts exactly as before; this is tested for every deployed host configuration (master, slave, SlpSoftware, ASF). - Mail is switched on only by setting `Email__Smtp__Host`, and it only turns ON when the whole mail configuration is valid: `App__PublicBaseUrl` (https, no path), `Email__FromAddress`/`Email__FromName` (committed defaults), `Email__Smtp__Username` together with `Email__Smtp__Password`, and sane port, timeout, colour and logo values. **A half-finished or wrong mail configuration never stops the host from starting** (decided by Bryan after the 2026-11-08 incident): the host starts with mail OFF (`emailEnabled=false`, all mail UI hidden, the copy-link flow keeps working) and logs ONE Error line, `mail_configuration_invalid`, that names each missing or invalid setting (names only, never values or secrets; Sentry sees it). Check the log after changing mail settings. Set `App__PublicBaseUrl` together with `Email__Smtp__Host`. - Optional: `Identity__Invitation__ExpiryHours` (24), `Identity__PasswordReset__TokenLifetimeMinutes` (60), `Identity__PasswordReset__CooldownMinutes` (5), `App__DefaultLanguage` (nl), `Email__AllowedFromAddresses__0..n`, `Website__LogLevel`. - Incident 2026-11-08: ASF test returned 502 after a restart because `Email__Smtp__Host` was set but `App__PublicBaseUrl` was not (the start-up validation at that time refused a half-configured mail setup). Not a deploy without mail configuration. Since changed: the soft behaviour above. ## Which sender is used, and what the server must accept (update 2026-11-08) The `From:` address of every mail is decided in this order: (1) the sender chosen in the site settings (Mail card), if it is still on the allowlist; otherwise (2) `Email:FromAddress` (environment variable `Email__FromAddress`, else the committed default of that host's `appsettings.json`). The committed default of the ASF host is `no-reply@slpsoftware.nl` (copied from SimpleDeckApp); the SlpSoftware host has the same. The SMTP server checks the `MAIL FROM` against the logged-in account (the envelope sender is always the `From:` address here, MailKit uses it). **So for `mail.andreaslop.nl` the ASF host must set**, in `shared/env`: `Email__FromAddress=` and `Email__AllowedFromAddresses__0=` (plus `Email__FromName`), where that address is one the SMTP account is allowed to use as sender. With the default `no-reply@slpsoftware.nl` the server is likely to refuse the sender (error code `rejected_sender`, SMTP 5xx at MAIL FROM) or not relay it. A change of the committed ASF default to an `@andreaslop.nl` address is a decision for Bryan (not made). **Diagnosis in the log** (Pi-Main journal): at start `mail_status enabled=true smtp_host=... smtp_port=... starttls=... default_from_domain=...`; per failed mail `identity_mail_failed code=... detail=... from_domain=... smtp_port=...`, where `detail` for a refused command is `SmtpCommandException phase=SenderNotAccepted|RecipientNotAccepted|MessageNotAccepted smtp_status=() reply=""`. The codes shown to the administrator: `rejected_sender`, `rejected_recipient`, `rejected`, `auth_failed`, `tls_failed`, `connection_failed`, `timeout`, `not_configured`, `unknown`. Never logged: credentials, addresses, tokens, links, the rest of a server reply. ## SMTP connection, security mode and timeouts (update 2026-11-09, for the Pi-Main journal questions) - **Security mode**: `Email__Smtp__EnableSsl=true` (the default) means MailKit `SecureSocketOptions.StartTls` (plain connection, then the STARTTLS upgrade; the normal setting for port 587). `false` means no encryption at all (`SecureSocketOptions.None`, only for a local catcher such as smtp4dev). Implicit TLS (port 465) is not supported. - **Authentication**: only when `Email__Smtp__Username` is set (then the password is required); MailKit picks the strongest mechanism the server offers. - **Timeout**: `Email__Smtp__TimeoutSeconds`, default **10**, allowed **1 to 120** (a value outside that switches mail off at start-up with an Error line naming the setting). It applies to EACH step separately (connect including the STARTTLS upgrade, login, send), so a slow login no longer uses up the time of the send; the worst case for one mail is three times the value. An administrator's request waits for it, so keep it modest; raise it (for example to 30) when the server is slow to log in. - **Per environment**: every SMTP setting lives in that host's `shared/env` (host, port, EnableSsl, username, password, timeout, `App__PublicBaseUrl`); hosts can differ (SlpSoftware `mail.slpsoftware.nl`, ASF probably `mail.andreaslop.nl`). - **Reading a failure in the journal**: `identity_mail_failed code= detail=... phase= timings="connect=120ms auth=4800ms(failed)" timeout_per_phase_s=10 from_domain=... smtp_port=...`. `timings` lists every step that ran and how long it took in milliseconds; the step marked `(failed)` is where it went wrong. MailKit does the STARTTLS upgrade inside the connect step, so "connect" covers the TCP connection, the greeting and the TLS upgrade together. Timeout codes: `timeout_connect`, `timeout_auth`, `timeout_send` (the screen text names the step). For a refused command the `detail` already holds the phase, the SMTP status code and the redacted first line of the server reply (since daaadcb). Nothing in the line is secret: no credentials, no addresses, no tokens. - **Typical readings**: `auth_failed` with `phase=AUTH` = wrong username or password (and repeated failures can make a server throttle or block the client address, for example fail2ban); `timeout_auth` = the server accepted the connection but took too long to answer the login (slow authentication backend, or a throttle); `timeout_connect` = no greeting or STARTTLS in time (firewall, wrong port, server down); `timeout_send` = the server stalled while taking the message.