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

Phase 1 of the email-integration project provisions two Postmark accounts. Neither account hosts any Postmark servers yet at this phase; server creation is performed in later phases (Phase 3 for the Corporate / Free Kanban Tool server, Phase 4 onwards for per-partition runtime servers).

Account name	Plan	Purpose	Partitions served
`PostmarkProd`	Platform	Production-grade email delivery	`prod`, `demo` (Alpha001); Corporate tooling
`PostmarkNonProd`	Platform	Sandbox / development delivery	`dev`, `stage` (Alpha002); developer testing

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.

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:

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.
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.

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.

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 workflow

A scheduled GitHub Actions workflow (external-resources-drift.yml in the infrastructure repository) asserts on a monthly cadence that the external resources declared in platform/postmark-service.ts and platform/one-password.ts are reachable and responding.

The workflow:

Authenticates to 1Password using OP_SERVICE_ACCOUNT_TOKEN (the one GitHub Actions secret provisioned for this purpose; never a Postmark token directly).
Resolves every op:// reference declared in the platform files, asserting each returns a non-empty value.
For each Postmark account whose credential resolves, issues a benign Account API call and asserts a 2xx response.
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
Free Kanban Tool Send Runbook	Server identity, token resolution, `From:` constraints, TypeScript SDK and curl recipes, troubleshooting for the `FreeKanbanTool` server (Phase 3)
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