# Code Generation Plan — CMS-U5 contact-mail (mail + retry) Phase 2, on the rebased branch (base `origin/master` `e671078`). Inputs: contract § 4 (store first, mail after commit, no personal data in logs, From = fixed site sender, Reply-To = visitor), requirements FR-D, SLS decision "new MailKind, do not change existing mail code", CMS-U3/U4 seams (`IContactMailSender`, `ContactMessage.MailStatus/MailAttempts/MailError/NextMailAttemptAt`, resend endpoint). Nothing is deployed; `Contact:Enabled` stays off. ## Findings on the merged master (Core/Email) - `IEmailSender.SendAsync(OutgoingMail)` returns a `MailSendResult(Sent, ErrorCode)`; never throws. `IMailAvailability.IsEnabled` is the single answer to "can this host send mail" (SMTP host set and configuration valid). `ISiteSettingsService.GetEffectiveSenderAsync` gives the effective From address/name (already checked against `Email:AllowedFromAddresses`). `ILanguageResolver` + `IMailTemplateRenderer` render subject/HTML/text from a static catalog per `MailKind` (nl/en), with dark-mode classes (`DarkPage`/`DarkCard`). - The renderer's layout has a heading, a greeting, one intro paragraph, an optional button and a note. A contact mail also needs a block with the visitor's name, e-mail address, subject and message, and the mail needs a `Reply-To`. `OutgoingMail` has no reply-to member and `MailModel` has no list of details. - `SmtpEmailSender` already classifies failures into short codes (`auth_failed`, `rejected_recipient`, `timeout_*`, ...); those codes are what `ContactMessage.MailError` stores. ## Decisions 1. **Additive changes in the shared mail code (needs ASF/SLS consent, nothing existing changes behaviour)**: `MailKind.ContactMessage` (+ nl/en catalog entry); `MailModel` gets an optional `IReadOnlyList? Details` (label/value pairs; values HTML-encoded, line breaks kept as `
` in HTML and plain lines in text, rendered inside the existing card with the existing muted/dark classes so the dark-mode contrast is kept); `OutgoingMail` gets optional `ReplyToAddress`/`ReplyToName`, applied by `SmtpEmailSender` (control characters stripped, address validated with `EmailAddressRules`). No other change to those files. 2. **The visitor never waits for SMTP.** The submit request no longer sends mail inline (U3 did a no-op call there). It stores the message with `MailStatus=Pending` and `NextMailAttemptAt=now` and wakes the sender in-process (a `Channel` signal); the mail goes out within seconds in the background. Resend (admin request) still sends inline, as U4 does. 3. **Retry job** `ContactMailService : BackgroundService` — wakes on the signal and every `Contact:Mail:SweepSeconds` (default 120). Selects rows with `Status != Spam`, `MailStatus in (Pending, Failed)`, `MailAttempts < MaxAttempts` and `NextMailAttemptAt <= now` (or null), oldest first, batches of 20. Each row is **claimed** first (`NextMailAttemptAt = now + 5 min`, saved) so two instances never mail the same message; then sent. Success: `Sent`, error cleared. Failure: `Failed`, `MailError` = the short code, `MailAttempts++`, `NextMailAttemptAt = now + backoff[attempts]` with backoff 5 min, 15 min, 1 h, 6 h, 24 h (configurable list); after `Contact:Mail:MaxAttempts` (default 6) it stays `Failed` until an administrator resends (resend ignores backoff and the maximum). 4. **When mail cannot be sent at all** (`IMailAvailability.IsEnabled` false or no valid `Contact:RecipientEmail`): rows stay `Pending`, no attempt is counted, nothing is retried in a loop; the admin detail shows why (`mailError` = `disabled` / `recipient_not_configured`). They are picked up automatically once mail is configured. 5. **Addresses**: recipient `Contact:RecipientEmail` is **environment only** for the Andrea site (no address in committed config); the SLP host may keep it in its own appsettings (SLS to confirm). From = `ISiteSettingsService.GetEffectiveSenderAsync` (allow-listed); Reply-To = visitor address and display name. Mail subject is fixed text from the catalog ("Nieuw bericht via {site}"); no visitor-supplied text goes into the subject or any header except Reply-To. 6. **Privacy**: no address, name or message in any log line, exception or Sentry event; only message id, attempt number and the short error code. `SmtpFailure.Describe` output stays out of the contact logs (it may quote reply text). 7. Admin API additive field: the message detail gets `nextMailAttemptAt` (nullable) so the UI can show "next attempt at ...". 8. The Andrea host gets the Contact module reference only when SLS/Bryan decide the ASF website uses the form (out of scope here); the module works there unchanged. ## Steps - [x] **Step 1 — Shared mail code, additive**: `MailKind.ContactMessage`, catalog texts (nl/en), `MailModel.Details`, `OutgoingMail.ReplyTo*`, `SmtpEmailSender` reply-to; renderer tests (see below). Show the diff of the three shared files to SLS before moving on. - [x] **Step 2 — Contact mail sender**: `ContactMailSender : IContactMailSender` (replaces the no-op; renders, builds the Reply-To, calls `IEmailSender`, maps the `MailSendResult` to `Sent/Failed` + code; returns `Skipped` for "disabled"/"no recipient"). - [x] **Step 3 — Pipeline change**: `ContactSubmissionService` stops sending inline, sets `NextMailAttemptAt`, signals `IContactMailSignal`. - [x] **Step 4 — Retry/background service** `ContactMailService` (claim, backoff, max attempts, signal, disabled handling) and options `Contact:Mail:*` (`SweepSeconds`, `MaxAttempts`, `BackoffMinutes`), `Contact:RecipientEmail`. - [x] **Step 5 — Admin**: detail gets `nextMailAttemptAt`; resend uses the real sender; OpenAPI regenerated. - [x] **Step 6 — Tests**: renderer (every visitor value HTML-encoded, newline handling, subject contains no visitor text, nl/en, dark-mode classes present, text part); sender with a fake `IEmailSender` (To/From/Reply-To/subject, control characters in the display name never reach a header, result codes mapped, disabled and missing recipient give `Skipped`); retry service (only due rows, spam never, backoff schedule exactly as configured, max attempts, claim prevents a second sender, signal wakes it, disabled mail leaves rows untouched and uncounted, resend ignores backoff); submission service no longer calls the sender and signals; no personal data in any log (extends the existing log-capture tests); **pipeline** on the real host with a capturing `IEmailSender` registered in the test host: submit -> mail captured within seconds and row `sent`; failing sender -> `failed` + code + next attempt; resend `mailed:true`; mail disabled -> rows pending. - [x] **Step 7 — Verification (automatic)**: build; all test projects incl. pipeline tests on a temporary MariaDB (removed afterwards). Optionally one manual end-to-end against smtp4dev if it is available locally (not a gate). - [x] **Step 8 — Docs/commit**: summary (config keys, behaviour table, shared-file diff), update `phase-1-handoff.md` routes/keys; one commit; no push. ## Explicitly NOT touched Existing mail kinds and their texts/behaviour, identity mail flow, `IMailAvailability`, site settings, SMTP credentials handling, the public routes' contract (still `202` immediately), the availability gate. ## Risks / questions for approval 1. OK to make the three **additive** changes in shared mail code (`MailTypes.cs`, `MailTemplateRenderer.cs`, `SmtpEmailSender.cs`)? Alternative without touching them: a plain-text-only contact mail built in the Contact module with no Reply-To header (worse: no one can reply by pressing Reply). I recommend the additive change. 2. `Contact:RecipientEmail` for the SLP host: committed in its appsettings or environment only? 3. Backoff 5 min / 15 min / 1 h / 6 h / 24 h and 6 attempts: acceptable?