Postmark Service

Postmark is the external Email Service Provider (ESP) that Arda uses to deliver transactional email on behalf of its tenants and its own corporate tooling. This page is the operator’s entry point into the Postmark-specific layer of Arda’s OAM surface. It describes the account topology, where typed references live in the codebase, operational responsibilities, and the drift-detection cadence.

---

1. Role in Arda’s Stack

Postmark is a third-party managed service; Arda does not operate any email infrastructure. Arda’s relationship with Postmark follows the same declared-reference pattern used for all external resources in the infrastructure repository: the accounts themselves are provisioned and maintained outside of CDK, while the references to those accounts (credentials, API base URL, plan metadata) are typed constants declared under platform/ and consumed by IaC stacks and operator tooling.

The Postmark integration serves two distinct consumer groups:

Consumer group	Sending identity	Postmark account used
Corporate tooling (e.g., Free Kanban Tool)	freekanban.arda.ardamails.com	PostmarkProd
Application Runtime tenants (per-partition)	{tenant}.{partition}.ardamails.com	PostmarkProd (prod / demo partitions) or PostmarkNonProd (dev / stage partitions)

Each Postmark account is the account-as-tenant boundary: the account enforces sending-domain isolation, houses per-server delivery statistics, and owns the suppression lists for its sending domains. Arda’s partition-pair mapping (production accounts to PostmarkProd, non-production accounts to PostmarkNonProd) ensures that sandbox testing activity does not affect production-grade delivery reputation.

For the full DNS topology, including the zone hierarchy and Corporate vs Application Runtime zone separation, see the Architecture Overview.

---

2. Account Inventory

Two Postmark accounts span the platform, each grouping the partition Sender Signatures whose reputation should stay co-located.

Account name	Plan	Purpose	Partitions served	Sender Signature inventory
PostmarkProd	Platform	Production-grade email delivery	prod, demo (Alpha001); Corporate tooling	arda.ardamails.com (Corporate, Phase 3); prod.ardamails.com, demo.ardamails.com (Phase 4 per-partition)
PostmarkNonProd	Platform	Sandbox / development delivery	dev, stage (Alpha002); developer testing	dev.ardamails.com, stage.ardamails.com (Phase 4 per-partition)

Both accounts are on the Platform plan, which is the Arda-committed tier. The plan constant is declared in the platform/postmark-service.ts file in the infrastructure repository (Arda-cards/infrastructure) — see Section 3.

Per-partition Sender Signatures are registered automatically by the Pre-Deploy entry script (tools/register-partition-mail-signature.ts) run from amm.sh step 5.x.0.5 — see the Partition Mail Topology reference for the per-partition resource inventory (DNS records, IAM roles, SM secrets) created at the same time. Postmark Servers are still not created at provisioning time; per the Email Integration design, Servers are created at system Runtime by Tenant, not at deploy time. The only Server provisioned today is FreeKanbanTool (Phase 3).

Credential storage

Account-level API tokens authenticate Postmark Account API calls via the X-Postmark-Account-Token HTTP header. The tokens follow a two-tier storage model:

1. 1Password (system of record): tokens for both accounts are stored in two places:

   • Global-utility items in Arda-SystemsOAM: Postmark-Prod (field: credential) and Postmark-NonProd (field: credential). These qualified names disambiguate both accounts within the single cross-partition vault. They are used by CI drift-detection workflows (authenticated via OP_SERVICE_ACCOUNT_TOKEN) and by operator tooling that spans partitions.
   • Per-partition copies in partition vaults: each partition’s Arda-{Env}OAM vault holds an independently stored copy under the service-name-only title Postmark (e.g., op://Arda-ProdOAM/Postmark/credential). The vault name carries the environment; no qualifier is needed. These partition-scoped copies are created during Phase 4 and serve as the runtime credential source for each partition’s deploy tooling.

2. AWS Secrets Manager (runtime copy, Phase 4 onwards): each partition’s CDK deploy reads the account token from 1Password at deploy time and writes a partition-scoped copy into Secrets Manager. The ESO operator then projects the secret into the partition’s Kubernetes namespace, where the operations pod reads it as the HOCON property extras.email.postmarkAccountToken at startup. The runtime copy is never sourced from a GitHub Actions secret; it is always resolved from the 1Password reference at CDK deploy time.

For the full credential lifecycle and rotation procedures, see the Cross-Cutting Design — Secret Management.

---

3. Typed Reference in the Infrastructure Repository

The authoritative typed reference for Postmark accounts and API surface assumptions lives in the platform/postmark-service.ts file in the infrastructure repository (Arda-cards/infrastructure). This file is a Phase 1 deliverable.

The file exports:

• A PostmarkAccount type (name, credentialReference, and plan metadata).
• Constants POSTMARK_PROD_ACCOUNT and POSTMARK_NONPROD_ACCOUNT of type PostmarkAccount, each carrying the live op://Arda-SystemsOAM/... reference to the corresponding 1Password item.
• POSTMARK_ACCOUNT_API_BASE_URL — the Account API base URL Arda commits to.
• POSTMARK_PLAN — the plan name Arda commits to for both accounts.
• A version-pin metadata block naming the Postmark API surface assumptions captured in the API observations note, including an observation-note URL and a freshness date after which re-validation is recommended.

No other file in infrastructure/src/main/cdk/ constructs op://Arda-SystemsOAM/Postmark-... strings inline; all consumers import the typed constants from this file (and from platform/one-password.ts for vault-level references). This rule is enforced by code review on all subsequent phases.

Related reference files

File	Purpose
platform/postmark-service.ts (infrastructure repo)	Account constants, API base URL, plan, version-pin metadata
platform/one-password.ts (infrastructure repo)	OAM_VAULT constant and typed 1Password item references for all project-scoped items

Cross-links

• Postmark API Observations — authentication models, error model, idempotency conventions, retry policy, webhook payload shapes, and version-pin assumptions.
• Operator Runbook — step-by-step instructions for provisioning the external resources (Phase 1), with troubleshooting tables and operator sign-off.
• Email Module Runbook — operating the running per-tenant email module (Phase 5b): drift assertions, configuration lock/unlock, verification troubleshooting, suppression.

---

4. Operational Responsibility

4.1 Postmark Console — primary OAM surface

The Postmark Console is the primary interface for operational management of the email service. Operators use it for:

• Delivery, bounce, and complaint statistics broken down by server.
• Per-domain DKIM, SPF, and DMARC verification status.
• Suppression-list management (hard bounces, spam complaints).
• Message-level diagnostics (search by recipient, subject, or MessageID).
• Post-provisioning webhook configuration changes.

Arda does not build a parallel OAM UI for the email service. Arda-side telemetry (structured logs, Prometheus metrics, CloudWatch alarms) supplements the Postmark Console with information specific to Arda’s use of the service — per-tenant aggregates, DNS-verification polling health, lifecycle transitions — but does not replace it. See Service Monitoring for the platform-wide monitoring model.

4.2 Drift-detection workflows

Two scheduled GitHub Actions workflows in the infrastructure repository assert on a monthly cadence that the Postmark surface matches the declarations in code:

• external-resources-drift.yml (Phase 1) — Account-level surface: the two account tokens resolve from 1Password and Account API calls return 2xx.
• runtime-platform-drift.yml (Phase 4 Run-6) — Per-partition mail surface: each partition’s Sender Signature exists on the right Postmark account, DNS records (SPF / DMARC / DKIM / Return-Path) match expectations, and cross-seam alignment between Postmark and live DNS holds.

The Phase 1 workflow’s operation is described below; the Phase 4 workflow follows the same shape with phase-4 / runtime-platform labels on the issues it opens. Both workflows share the helper modules under infrastructure/tools/lib/drift/ to avoid duplication.

The Phase 1 workflow:

The workflow:

1. Authenticates to 1Password using OP_SERVICE_ACCOUNT_TOKEN (the one GitHub Actions secret provisioned for this purpose; never a Postmark token directly).
2. Resolves every op:// reference declared in the platform files, asserting each returns a non-empty value.
3. For each Postmark account whose credential resolves, issues a benign Account API call and asserts a 2xx response.
4. On any failure, opens a GitHub issue labelled drift,phase-1,external-resources containing the run URL and a summary of the observed-vs-declared divergence.

Postmark account tokens are resolved at workflow runtime via the 1Password SDK; they are never stored as GitHub Actions secrets.

Failure handling: when a drift issue is opened, the on-call operator reads the run log linked in the issue, compares observed Postmark state to the declarations in infrastructure, and either reconciles manually (Postmark Console and/or operator tooling) or opens a follow-up to update the declarations. The issue is closed when the divergence is resolved.

---

5. References

Document	Description
Postmark API Observations	Arda’s design intent against the Postmark API surface: authentication models, error model, idempotency, retry policy, webhook shapes, version-pin assumptions
Operator Runbook	Manual provisioning steps for Phase 1 external resources, with troubleshooting and sign-off
Email Module Runbook	Operating the running per-tenant email module (Phase 5b): drift assertions, lock/unlock, verification, suppression
Email (functional design)	The module’s behavior: domain model, lifecycle, provisioning & sending, webhook ingestion, API
Free Kanban Tool Send Runbook	Server identity, token resolution, From: constraints, TypeScript SDK and curl recipes, troubleshooting for the FreeKanbanTool server (Phase 3)
Encryption-Key Rotation Runbook	Operator procedure for rotating each partition’s EmailEncryptionKey SM secret — the symmetric key the operations component uses to encrypt per-tenant Postmark server tokens at rest (Phase 4)
Partition Mail Topology	Per-partition mail surface — the four {partition}.ardamails.com sub-zones, NS-delegation chain, IAM role topology, and Postmark account binding (Phase 4)
Service Monitoring	Platform-wide monitoring model (Arda-side telemetry)
Architecture Overview — DNS Topology	DNS hierarchy: Corporate vs Application Runtime zone separation
Cross-Cutting Design — Secret Management	Full credential lifecycle, rotation procedures, and redaction contract
Cross-Cutting Design — OAM	Alerts, runbooks, and manual operation procedures
Phase 1 Requirements	Traceable requirements for the Phase 1 deliverables this page documents