pal-e-docs

Project: Postmark Email

project-postmark-email Project Page

active project-page
Project

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

Key Story Note Role Success Metric
iac-email <a href="story-postmark-email-iac-email">story-postmark-email-iac-email</a> Platform operator terraform plan shows no drift; new domain = one tfvars block
transactional-email <a href="story-postmark-email-transactional-email">story-postmark-email-transactional-email</a> App user Password reset email arrives within 30s with working link
inbound <a href="story-postmark-email-inbound">story-postmark-email-inbound</a> Platform operator Test emails queryable via MCP within 60s of sending

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

Repo Platform Role Status
ldraney/pal-e-platform Forgejo Postmark provider + module + DNS + inbound webhook Merged
ldraney/pal-e-services Forgejo Keycloak SMTP config + email docs Merged