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>
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)
- Add the keys above to
shared/envofandreaslopfotografie-test(mode 600 stays), restart the unit. Email__FromAddressstaysno-reply@slpsoftware.nl(the SMTP service's own domain). A sender on@andreaslop.nlonly after the check below.- 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 bothslpsoftware.nlandandreaslop.nlpublishv=spf1 a mx include:smtp.spf.ziggo.nl ~all). - That service must DKIM-sign for the
From:domain (adkim._domainkeyrecord exists for both domains; whether the service signs with it is not visible from outside). mail.slpsoftware.nlwill deliver@andreaslop.nlmail properly only if it may send/sign for that domain. DMARC isp=nonetoday (monitoring only).- Therefore the sender list is an allowlist: add an
@andreaslop.nladdress toEmail__AllowedFromAddressesonly 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):
- Which mailbox/account on
mail.andreaslop.nlis used, and whether it may send withno-reply@andreaslop.nl(or another address) asFrom. Then ASF setsEmail__FromAddressandEmail__AllowedFromAddresses__naccordingly (the committed ASF defaultno-reply@slpsoftware.nlis only a placeholder until then). SlpSoftware keepsmail.slpsoftware.nl. - 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. - DKIM: a
dkim._domainkey.andreaslop.nlrecord exists; confirm the server signs with that key. DMARC isp=none(monitoring only). - Credentials for that account go into the ASF test unit's
shared/envby 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__Usernametogether withEmail__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. SetApp__PublicBaseUrltogether withEmail__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__Hostwas set butApp__PublicBaseUrlwas 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 MailKitSecureSocketOptions.StartTls(plain connection, then the STARTTLS upgrade; the normal setting for port 587).falsemeans 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__Usernameis 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 (SlpSoftwaremail.slpsoftware.nl, ASF probablymail.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=....timingslists 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 thedetailalready holds the phase, the SMTP status code and the redacted first line of the server reply (sincedaaadcb). Nothing in the line is secret: no credentials, no addresses, no tokens. - Typical readings:
auth_failedwithphase=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.