pal-e-docs

Review: Deliverability validation: mail-tester + e2e password reset (ISS)

review-1860-2026-07-17 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Issue type is Spike. Checked against template-issue-spike.
  • [x] Type -- "Spike"
  • [x] Lineage -- "Final gate -- depends on all other stalwart-email tickets"
  • [x] Repo -- ldraney/pal-e-services
  • [x] Question -- present with sub-questions
  • [x] Deliverables -- 4 deliverables listed
  • [x] Time-box -- "2 hours"
  • [x] Related -- present
  • [ ] Missing required spike deliverable: docs/{topic}.md -- spike template mandates a durable docs file artifact

Traceability

  • [x] story:transactional-email label -- "Transactional Email Flows"
  • [x] story note verified -- found in project-postmark-email user-stories section (row: transactional-email, role: App user)
  • [x] arch:keycloak label -- Keycloak component
  • [x] arch note verified -- arch-keycloak note exists in pal-e-docs (project: pal-enterprises, note_type: doc)
  • [x] Forgejo issue -- ldraney/pal-e-services#168, open
  • [ ] type label MISMATCH -- board item has type:feature but issue body says Type: Spike. [LABEL] Change to type:spike

File Targets

Spike type -- no existing file targets to verify. Expected output is a new docs/ file (not present in issue deliverables).
Codebase verification of current SMTP state:
  • [x] pal-e-services/terraform/keycloak.tf -- SMTP configuration uses var.postmark_iss_server_token as default auth
  • [x] ISS realm in tfvars -- has Postmark SMTP configured (smtp.postmarkapp.com, noreply@intelligentstaffingsystems.ai), reset_password_allowed = true
  • [x] Landscaping realm -- NO SMTP configured (no smtp block in tfvars)
  • [x] Westside realm -- uses Gmail SMTP (smtp.gmail.com), reset_password_allowed = false

Repo Placement

OK -- issue filed on ldraney/pal-e-services, Repo field matches. Validation spike touches email config in pal-e-services. Postmark Terraform provider lives in pal-e-platform but that is a dependency, not a target for this spike.

Dependencies

Issue states "Blocked by: ALL other stalwart-email tickets" but uses the stale project name and lacks specific references.
Board state (board-postmark-email):
  • Validation: #1801 (pal-e-platform#517, Postmark Terraform -- closed), #1802 (pal-e-services#174, Keycloak SMTP via Postmark -- closed)
  • Backlog: #1861 (pal-e-services#165, DNS landscaping -- open), #1862 (pal-e-services#166, DNS westside -- open), #1863 (pal-e-services#167, Keycloak SMTP both realms -- open), #1859 (pal-e-services#169, docs onboarding -- open)
Critical dependency for ISS validation: #1801 and #1802 are in validation/closed -- ISS Postmark infrastructure is ready. The backlog items (#165, #166, #167) are for landscaping/westside domains which are NOT ready. This spike can proceed for ISS domain alone without waiting for those.

Acceptance Criteria

Deliverables (spike format) are mostly testable:
  • "mail-tester.com score report" -- requires browser automation to send test email and capture score. Testable but manual.
  • "Successful password reset test" -- requires end-to-end browser flow through Keycloak + email inbox. Testable with agent browser tools.
  • "Email header verification" -- can be checked programmatically via email headers or mxtoolbox. Testable.
  • "Follow-up tickets" -- meta-deliverable, always achievable.
Issue: deliverables reference "both domains (landscaping-assistant.app, westsidekingsandqueens.com)" but neither domain uses Postmark. Only ISS (intelligentstaffingsystems.ai) has Postmark SMTP configured.

Blast Radius

This is a read-only validation spike -- no code changes expected, only a docs file and follow-up tickets. Blast radius is minimal.
Related concern: if deliverability issues are found (DNS misconfiguration, blacklisting), fixes would touch pal-e-platform Terraform (DNS records) and potentially pal-e-services (SMTP config). These are documented as follow-up ticket deliverables.

Decomposition Assessment

4 deliverables across 1 repo. 2-hour timebox. No decomposition needed -- fits in a single agent pass.

Recommendation

  • [LABEL] Change type:feature to type:spike on board item #1860
  • [BODY] Replace domain references: issue body references landscaping-assistant.app and westsidekingsandqueens.com but only ISS (intelligentstaffingsystems.ai) has Postmark SMTP configured. Update Question and Deliverables to reference ISS domain.
  • [BODY] Replace "stalwart-email project" with "postmark-email project" in Related section
  • [BODY] Replace "Blocked by: ALL other stalwart-email tickets" with specific references: pal-e-platform#517 (done), pal-e-services#174 (done). Note that backlog items #165/#166/#167 are for other domains and not blockers for ISS validation.
  • [BODY] Add docs/deliverability-validation.md as a required deliverable per spike template