Postmark Transactional Email

Vision

Reliable transactional email for all pal-e platform apps via Postmark SaaS. Keycloak password resets and email verification flows work out of the box for any onboarded domain. Infrastructure fully managed via Terraform.

User Stories

Architecture

Architecture notes pending. Key decisions:

• Postmark SaaS over self-hosted (Hetzner blocks port 25)
• marcus-carey/postmark Terraform provider v1.0.0 (source: registry.terraform.io/marcus-carey/postmark — not on OpenTofu registry)
• DNS via existing GoDaddy provider
• Keycloak dynamic "smtp_server" block in keycloak.tf consumes Postmark config
• prevent_destroy on server resources (Postmark API blocks server deletion)
• Dedicated SMTP tokens (PM-T-outbound-*) for Keycloak SMTP auth — server tokens reserved for API only
• Shared inbound webhook endpoint via Tailscale funnel — one nginx:alpine pod serves all Postmark servers, HTTP Basic Auth, auto-generated creds in k8s Secret

Board

board-postmark-email

Status

• Postmark account created and verified
• intelligentstaffingsystems.ai domain verified (DKIM + Return-Path)
• Server API token and Account API token stored in ~/secrets/postmark/
• API CRUD validated (create/read/update work; delete blocked by Postmark)
• PR #518 merged (2026-07-05) — Postmark provider, module, DNS records for ISS
• PR #175 merged (2026-07-05) — Keycloak SMTP config for password reset + email verification
• PR #186 merged (2026-07-17) — Postmark email integration guide + Keycloak SMTP docs cross-reference
• SMTP token migration (2026-07-17) — ISS realm switched from server token to dedicated SMTP token, applied via tofu
• Postmark account submitted for approval (2026-07-17) — external delivery blocked until approved (ErrorCode 412)
• Same-domain test email delivered successfully
• Both infra items in validation — remaining: Postmark account approval, E2E password reset test, mail-tester check
• PR #582 merged (2026-08-03) — MX record for intelligentstaffingsystems.ai inbound email
• Inbound email confirmed working (2026-08-03) — emails queryable via search_inbound_messages MCP tool
• PR #584 merged (2026-08-04) — Shared inbound webhook endpoint via Tailscale funnel with HTTP Basic Auth
• PR #586 merged (2026-08-05) — Fixed godaddy-tofu CI checksum mismatch (pre-built release binary)
• Webhook deployed and e2e tested (2026-08-05) — full chain verified: send email → webhook → inbound stream → queryable via MCP
• Bug #587 discovered — tofu apply clears InboundDomain (not managed by postmark module); restored manually, fix pending

Milestones

• 2026-07-05: Terraform provider and module merged (PR #518)
• 2026-07-05: Keycloak SMTP config merged (PR #175)
• 2026-07-17: SMTP token migration — Keycloak ISS realm switched to dedicated SMTP token
• 2026-07-17: Postmark integration docs merged (PR #186)
• 2026-07-17: Postmark account submitted for approval
• 2026-08-03: MX record and inbound email setup (PR #582)
• 2026-08-05: Shared inbound webhook endpoint deployed and e2e tested (PRs #584, #586)

Repos

story: Inbound Email Webhook

Role

Platform operator

Key

inbound

Want

As a platform operator, I want a shared webhook endpoint that Postmark can POST to for any app's inbound email

So That

So that inbound emails are reliably delivered and queryable via the MCP/API for test account registration and future inbound workflows

Acceptance Criteria

• Shared webhook endpoint deployed in k8s via Tailscale funnel
• Endpoint returns 200 on POST (ACK only, no processing)
• HTTP Basic Auth secures the endpoint
• Any app's Postmark server can point InboundHookUrl to the shared endpoint
• Inbound emails queryable via search_inbound_messages MCP tool

Success Metric

Send email to test@intelligentstaffingsystems.ai, query via MCP within 60 seconds

Related Architecture

• arch-deployment-postmark — deployment diagram

Related

• project-postmark-email — parent project page
• board-platform-playbook — ticket tracks on platform-playbook board

story: Transactional Email Flows

Role

App user

Key

transactional-email

Want

As an app user, I want to receive password reset and email verification emails

So That

So that I can recover my account and verify my identity when signing up

Acceptance Criteria

• Password reset email arrives when "forgot password" is clicked on Keycloak login
• Email verification email arrives when a new user registers
• Emails come from a verified domain (not Gmail)
• SMTP config managed in Terraform, not manually in Keycloak

Success Metric

E2E: trigger password reset → email arrives within 30 seconds with working reset link

Related Architecture

• Architecture notes pending creation for postmark-email project

Related

• project-postmark-email — parent project page
• board-postmark-email — project board (tickets reference this story)

story: IaC Email Infrastructure

Role

Platform operator

Key

iac-email

Want

As a platform operator, I want to manage email server and domain infrastructure via Terraform/OpenTofu

So That

So that email infrastructure is reproducible, auditable, and extensible to new domains without manual setup

Acceptance Criteria

• Postmark servers created/managed via Terraform
• DNS records (DKIM, Return-Path) managed via Terraform
• New domain onboarding requires only a tfvars entry
• Existing manually-created resources imported into state

Success Metric

terraform plan shows no drift after import; new domain can be added with a single tfvars block

Related Architecture

• Architecture notes pending creation for postmark-email project

Related

• project-postmark-email — parent project page
• board-postmark-email — project board (tickets reference this story)

Verdict: PASS

Ticket

ldraney/postmark-account-sdk#2 (board item #1915 on board-postmark) — Python SDK for all 23 Postmark Account API endpoints with full integration test suite.

Merged PR: #5 — squash-merged as daeee3d on origin/main.

Environment

Tier 1 (local). SDK is a Python library — no deployment target. Validation = merge commit on origin/main, package installs, tests pass against real Postmark Account API.

Test runner: Python 3.14.5, pytest 9.1.1, httpx 0.28.1. API token sourced from ~/secrets/postmark/account/.env.

Checks

Regression Check

SDK is a new library with no prior version — no regressions possible. Verified the package does not conflict with existing Python environment (clean venv install succeeded with no dependency conflicts).

Discovered Issues

ruff format --check flags 1 markdown file (docs/user-story.md) for code-block formatting. This is cosmetic — all 16 Python source and test files are properly formatted. Non-blocking; may be addressed in a future cleanup pass.

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag -- "none" (appropriate for docs PR)
• [x] Acceptance Criteria -- 7 items
• [x] Test Expectations -- "No tests -- docs only PR"
• [x] Constraints
• [x] Checklist -- missing "Tests pass" but justified by docs-only nature
• [x] Related

Traceability

• [x] story:sdk label present on board item
• [ ] story note MISSING -- project-postmark-email user-stories section has entries for iac-email and transactional-email only; no sdk entry. [SCOPE] Create user story entry for sdk on project-postmark-email user-stories section.
• [x] arch:api label present on board item
• [ ] arch note WRONG PROJECT -- arch-api note exists but belongs to prediction-assistant (Kalshi), not postmark. [SCOPE] Create architecture note for postmark API component (e.g. arch-postmark-api or repurpose arch-api slug with postmark content).
• [x] Forgejo issue -- ldraney/postmark-account-sdk#1, open

File Targets

• [x] ~/postmark-email/postmark-account-api.yaml -- verified exists (29k), valid swagger spec for Postmark Account-level API v0.9.0
• [x] ~/forgejo-sdk/ -- verified exists as reference repo
• [ ] ~/forgejo-sdk/ -- ISSUE: issue Constraints say "Follow the pattern established by ~/forgejo-sdk" but forgejo-sdk has no docs/ directory, no CLAUDE.md symlink, no architecture/user-story/acceptance-criteria docs. The proposed structure is new, not a clone of forgejo-sdk's pattern.
• [ ] ~/postmark-account-sdk/ -- NOT cloned locally. Repo exists on Forgejo with only README.md. Agent will need to clone before working.
• [x] All 6 target files are "to be created" -- no pre-existing file verification needed beyond sources

Repo Placement

OK. Issue filed on ldraney/postmark-account-sdk, ### Repo section matches. Single-repo scope.

Dependencies

• Sprint 2: SDK implementation (#1915, 5pt) depends on this docs PR completing first -- documented implicitly by sprint numbering
• Sprint 3: Woodpecker pipeline (#1917, 2pt) depends on Sprint 2
• No items currently in_progress blocking this ticket
• Sibling Sprint 1 docs PRs for other repos (#1910 postmark-server-sdk, #1912 postmark-server-mcp, #1913 postmark-account-mcp) are independent and can run in parallel

Acceptance Criteria

• [x] 7 AC items, all verifiable by an agent (file existence, symlink check, content inspection)
• [ ] AC #7 "All docs reference the Postmark Account API endpoints from the swagger spec" is vague -- does not specify which endpoints or what "reference" means. An agent could interpret this very broadly or very narrowly. Consider specifying: "docs/architecture.md lists all endpoint groups from the swagger spec".

Blast Radius

Minimal. Docs-only PR in a nearly empty repo. Swagger spec is copied, not modified at source. No downstream consumers affected.

Decomposition Assessment

6 file targets in 1 repo, 7 AC items. The 7 AC count exceeds the >5 threshold, but all work is documentation generation from a swagger spec following a template. Estimated agent time: under 5 minutes. No decomposition needed -- docs generation is inherently fast and the files are tightly coupled (they all reference the same spec).

Recommendation

• [SCOPE] Create user story entry for sdk on project-postmark-email user-stories section. Currently only iac-email and transactional-email stories exist.
• [SCOPE] Create postmark-specific architecture note. The current arch-api note (slug) belongs to prediction-assistant. Options: create arch-postmark-api, or create a new note with a postmark-scoped slug.
• [BODY] Constraints section: clarify or remove "Follow the pattern established by ~/forgejo-sdk" -- that repo has no docs/ directory, no CLAUDE.md, and no architecture/user-story/acceptance-criteria docs. The proposed structure is original, not a pattern clone. Suggest: "Establish the docs pattern for postmark SDK repos" or reference a different exemplar.
• [BODY] Related section: change postmark to postmark-email to match the actual project slug in pal-e-docs.

Verdict: APPROVED

Re-review (R2) of board item #1860. All 5 issues from R1 (review-1860-2026-07-17) have been resolved in a complete body rewrite.

R1 Issues -- Resolution Status

• [x] [BODY] Replace domain references (landscaping/westside to ISS) -- body now exclusively references ISS (intelligentstaffingsystems.ai)
• [x] [LABEL] Change type:feature to type:spike -- board item labels now type:spike,arch:keycloak,story:transactional-email,domain:iss
• [x] [BODY] Replace "stalwart-email project" references -- no stalwart references remain
• [x] [BODY] Replace generic "Blocked by: ALL other stalwart-email tickets" with specific references -- Prerequisites section now lists pal-e-platform#517 and pal-e-services#174 with resolution status
• [x] [BODY] Add docs/ deliverable per spike template -- docs/postmark-deliverability.md added to Deliverables

Template Completeness

Issue type is Spike. Checked against template-issue-spike.

• [x] Type -- "Spike"
• [x] Context (serves as Lineage) -- references parent issues pal-e-platform#517 and pal-e-services#174
• [ ] Repo -- missing section header, but implied (issue filed on ldraney/pal-e-services). Minor.
• [x] Question -- clear yes/no framing: "Does the ISS Keycloak realm deliver password reset emails via Postmark with acceptable deliverability?"
• [x] Deliverables -- 4 items including docs/postmark-deliverability.md
• [x] Timebox -- "2 hours"
• [ ] Related -- missing section header, but related issues referenced in Context and Prerequisites. Minor.
• [x] Prerequisites (bonus) -- specific issue cross-references with completion status
• [x] Test Plan (bonus) -- 7-step validation procedure
• [x] Acceptance Criteria (bonus) -- 4 measurable criteria

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, metric: "Password reset email arrives within 30s with working link")
• [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
• [x] type:spike label -- matches issue body Type header
• [x] domain:iss label -- matches issue scope (ISS only)

File Targets

Spike type -- no existing file targets to verify. Expected output is docs/postmark-deliverability.md (correctly listed as deliverable). No codebase changes expected.

Repo Placement

OK -- issue filed on ldraney/pal-e-services. Spike validates Keycloak SMTP configuration which lives in pal-e-services. Postmark Terraform provider lives in pal-e-platform but that is a resolved dependency (#517, closed), not a target for this spike.

Dependencies

Prerequisites section documents specific resolved dependencies:

• [x] pal-e-platform#517 -- Postmark provider + DNS for intelligentstaffingsystems.ai (closed)
• [x] pal-e-services#174 -- Keycloak SMTP via Postmark configured (closed)
• [ ] ISS Keycloak realm provisioned and accessible (runtime check before testing)

Board state confirms: #1801 (pal-e-platform#517) and #1802 (pal-e-services#174) are in validation column. No blockers remain for this spike.

Acceptance Criteria

4 criteria, all measurable and testable by an agent:

• "Password reset email arrives in inbox (not spam)" -- testable via e2e browser flow + email API
• "mail-tester.com score >= 9/10" -- testable via browser automation
• "SPF, DKIM, DMARC all pass" -- testable via email header inspection
• "Results documented in docs/postmark-deliverability.md" -- verifiable file output

Blast Radius

Read-only validation spike -- no code changes expected, only a docs file output and potential follow-up tickets. Blast radius is minimal.

Decomposition Assessment

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

Recommendation

No action needed. All R1 issues resolved. Ticket is ready for execution.

Minor template compliance notes (not blocking):

• Missing ### Repo header -- information is implied by issue placement on pal-e-services
• Missing ### Related header -- related issues are referenced in Context and Prerequisites sections
• ### Context used instead of ### Lineage -- serves the same purpose with more detail

These are cosmetic and do not affect agent executability.

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

Verdict: APPROVED

Re-reviewed 2026-07-05. Original verdict was NEEDS_REFINEMENT due to incorrect file path and missing arch note. The [BODY] fix has been applied (k3s.tfvars corrected to terraform/k3s.tfvars, line reference updated). The [SCOPE] item (missing architecture notes) is a project-level gap acknowledged on the project page and does not block ticket execution.

Template Completeness

• [x] Type — Feature
• [x] Lineage — present, correctly notes dependency on pal-e-platform issue
• [x] Repo — ldraney/pal-e-services
• [x] User Story — present
• [x] Context — present, thorough
• [x] File Targets — 3 targets listed
• [x] Feature Flag — none (appropriate)
• [x] Acceptance Criteria — 8 items
• [x] Test Expectations — present
• [x] Constraints — present
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:transactional-email label — Transactional Email Flows
• [x] story note verified — found in project-postmark-email user-stories section
• [x] arch:keycloak label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-keycloak note exists yet. Project page acknowledges "Architecture notes pending." Does not block ticket.
• [x] Forgejo issue — pal-e-services#174, open

File Targets

• [x] terraform/k3s.tfvars — verified: exists (symlink to ../../secrets/pal-e-services/k3s.tfvars). Path corrected from original k3s.tfvars.
• [x] terraform/variables.tf — verified: exists, already has smtp variable type definition (line 129-130)
• [x] terraform/keycloak.tf — verified: exists, dynamic "smtp_server" block confirmed at lines 54-68 (handles host, port, from, starttls, ssl, auth)

Repo Placement

Correct. Keycloak realm SMTP config belongs in pal-e-services. Issue correctly notes that module changes belong in pal-e-platform.

Dependencies

Depends on pal-e-platform#517 (Postmark provider/module). Documented in Lineage. The Postmark server API token output from #517 is consumed as SMTP credentials here. Both items are on board-postmark-email.

Acceptance Criteria

8 ACs. 6 verifiable via terraform and Postmark dashboard. 2 require manual E2E testing (password reset flow, registration verification). Test Expectations correctly notes manual validation. All criteria are clear and testable.

Blast Radius

Medium but well-scoped. SMTP config changes affect target realms only. Westside-basketball SMTP block excluded. Test mode limits blast to verified domains.

Decomposition Assessment

3 file targets in 1 repo, 8 ACs. Estimated agent work under 5 minutes. No decomposition needed.

Recommendation

• [SCOPE] Create architecture notes for postmark-email project as a follow-up. Does not block this ticket.

Verdict: APPROVED

Re-reviewed 2026-07-05. Original verdict was NEEDS_REFINEMENT due to missing arch note. The [SCOPE] item (missing architecture notes) is a project-level gap acknowledged on the project page ("Architecture notes pending") and does not block ticket execution. Issue body is template-complete and all file targets verified.

Template Completeness

• [x] Type — Feature
• [x] Lineage — present
• [x] Repo — ldraney/pal-e-platform
• [x] User Story — present
• [x] Context — present, thorough
• [x] File Targets — 7 targets listed
• [x] Feature Flag — none (appropriate)
• [x] Acceptance Criteria — 8 items
• [x] Test Expectations — present
• [x] Constraints — present
• [x] Checklist — present
• [x] Related — present

Traceability

• [x] story:iac-email label — IaC Email Infrastructure
• [x] story note verified — found in project-postmark-email user-stories section
• [x] arch:terraform label — present on board item
• [ ] arch note MISSING — [SCOPE] No arch-terraform or arch-deployment-postmark-email note exists yet. Project page acknowledges "Architecture notes pending." Does not block ticket.
• [x] Forgejo issue — pal-e-platform#517, open

File Targets

• [x] terraform/versions.tf — verified: exists, postmark provider not yet present (expected)
• [x] terraform/variables.tf — verified: exists
• [x] terraform/modules/postmark/ (main.tf, variables.tf, outputs.tf) — does not exist yet (expected, will be created). Parent dir terraform/modules/ exists with 12 existing modules as pattern reference.
• [x] terraform/main.tf — verified: exists
• [x] terraform/dns.tf — verified: exists

Repo Placement

Correct. Terraform provider, module, and DNS belong in pal-e-platform. Issue correctly notes that keycloak.tf changes belong in pal-e-services.

Dependencies

No blocking dependencies. This is the upstream issue that pal-e-services#174 depends on. Dependency is documented in #174's Lineage section.

Acceptance Criteria

8 ACs, all verifiable via terraform commands. Clear success criteria. Import commands for ISS server (ID: 19810066) are called out. All criteria are testable by an agent.

Blast Radius

Low. New provider and module addition. Does not modify existing infrastructure resources. DNS records are additive.

Decomposition Assessment

7 file targets in 1 repo, 8 ACs. Module creation (3 files) is a cohesive unit. Estimated agent work under 5 minutes. No decomposition needed.

Recommendation

• [SCOPE] Create architecture notes for postmark-email project as a follow-up. Does not block this ticket.