Files
SluijsensandClaude Sonnet 5.5 190deb0da8 Mail: timeout per stap met fase en verstreken tijd in het log
De SMTP-verzender gaf alle stappen samen een tijdsbudget; nu krijgt elke stap (verbinden met STARTTLS,
inloggen, versturen) zijn eigen volledige timeout. Bij een timeout noemt de code de stap
(timeout_connect, timeout_auth, timeout_send) en toont het log per stap de verstreken milliseconden.
TimeoutSeconds blijft instelbaar (standaard 10), bereik nu 1 tot 120. Infra-doc met veiligheidsmodus,
timeout en leeswijzer voor het journal.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-09 01:30:16 +01:00

11 KiB

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=<an address on andreaslop.nl> and Email__AllowedFromAddresses__0=<the same address> (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=<name>(<number>) reply="<first line of the server reply, addresses replaced by [adres], at most 120 characters>". 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=<code> detail=... phase=<connect|auth|send> 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.