Email Integration -- Project Goal

Goal

Enable Arda’s products and corporate systems to send transactional email on behalf of their users, with per-recipient deliverability isolation, secure credential management, and operational observability.

The project introduces email as a first-class platform capability serving two consumer populations:

1. Application Runtime tenants — each tenant of an Arda product operates its own verified sending domain.
2. Corporate consumers — Arda-owned tools that send on Arda’s behalf. The Free Kanban Tool is the founding consumer; subsequent Corporate consumers (e.g., HubSpot integration, marketing automation) plug into the same pattern.

A speculative third population — Arda’s platform itself sending operational email through a dedicated Infrastructure-level resource — is anticipated but is not exercised by this project.

The project also establishes the Corporate Resource Group as a runtime instance group of the Arda platform, peer to the existing Application Runtime instance group, with the Free Kanban Tool as its founding member.

Desired outcomes

Functional capabilities the platform must offer at the end of the project.

Tenant provisioning and lifecycle

• A new tenant can be configured with a dedicated sending domain. The required DNS records are requested, published, and verified automatically.
• A tenant’s email-sending capability is gated by verification of its sending domain (DKIM and Return-Path); the tenant cannot send until verified.
• A tenant’s email configuration can be locked, retried, or removed through the platform’s standard API surface, without ad-hoc operator action.

Sending and delivery tracking

• A consumer can request that an email be sent on behalf of a tenant. The request produces a delivery attempt and is observable end-to-end.
• Delivery, bounce, and spam-complaint events emitted by Postmark are received, authenticated, and reflected in the recorded status of the corresponding email job.

Corporate consumers

• The Free Kanban Tool sends transactional email from freekanban.arda.ardamails.com with full DKIM, SPF, and DMARC compliance.
• The Corporate Resource Group’s mail infrastructure (the arda.ardamails.com zone with SPF and DMARC records, NS-delegated from ardamails.com) is in place and serves as the foundation for future Corporate consumers.

Operability

• Periodic drift-detection asserts that live external resources (Postmark accounts, sending domains, 1Password items, GitHub Actions secrets) match the state declared in the infrastructure repository, surfacing any divergence as an investigation item.
• Operators and future implementors have a self-contained reference describing the Postmark API surface that informs implementation and operational diagnosis without requiring re-derivation from third-party documentation.
• Aggregate operational management of the email service is performed through the Postmark Console; the project does not build an Arda-side OAM surface for the email service.
• Documentation — new pages for the services introduced by this project, plus reconciliation of existing pages with the practices and designs adopted — is up to date at project end.

Implementation constraints

Constraints that must be honoured in any solution. Each is anchored in a recorded project decision (see Key decisions below).

Domain and DNS

• Mail traffic is anchored at the standalone domain ardamails.com; no Arda product domain (e.g., arda.cards) participates in the mail tree (DQ-009).
• Per-tenant sending domains follow the structure {config-slug}.{tenant-slug}.{partition}.ardamails.com uniformly across all Application Runtime partitions (DQ-001, DQ-002, DQ-003).
• Each Application Runtime partition owns its mail sub-zone ({partition}.ardamails.com); the root ardamails.com zone is static (DQ-010).
• Corporate sending traffic uses a dedicated zone arda.ardamails.com, NS-delegated from the root zone, peer to the partition zones.
• The mail-zone naming hierarchy reserves arda and the partition names at the ardamails.com level so they cannot be appropriated as tenant slugs in any partition zone.

Credentials and secrets

• Postmark account-level API tokens are stored in 1Password (the Arda-SystemsOAM vault) and resolved at deploy time and runtime via the 1Password SDK. They are never persisted as GitHub Actions secrets, as environment variables in checked-in files, or as deploy-pipeline context entries.
• Per-tenant Postmark server tokens are stored encrypted at rest in the database. The encryption key is per-partition and is projected to pods through External Secrets Operator (DQ-012).
• Exactly one GitHub Actions repository secret — the 1Password service-account token — is provisioned at the CI surface; CI workflows resolve every other downstream credential at runtime via the 1Password SDK.

Authentication

• Authentication for the email service is performed in-component, in the Ktor server configuration of each route. The Postmark webhook route is authenticated by a Bearer token validated by the receiving component itself; consumer-facing routes use the Application Runtime’s existing in-component authentication scheme (DQ-011).
• API-gateway-level authorisers for the email service are out of scope for this project. If and when the platform later adopts gateway-level authorisation as a cross-cutting concern, the email-service routes migrate alongside the rest.

Operations

• All resources — AWS, Postmark, 1Password, GitHub — are described declaratively in the infrastructure repository. Day-to-day reconciliation is operator-driven through dedicated scripts that source every value from versioned configuration; operators do not supply configuration values at invocation time.
• Implementation work for this project lands across four repositories: infrastructure (IaC declarations, operator CLIs, drift-detection workflows), operations (the email-sending capability and its API surface), common-module (supporting library additions consumed by the email module), and documentation (new pages and reconciliation of existing pages with practices adopted in this project).

Acceptance criteria

Capability-level outcomes that must be true for the project to be considered complete. Each is a black-box statement at the system boundary; the verification artifact produced during planning will decompose each into mechanical checks.

1. Tenant provisioning works end-to-end. A consumer that requests tenant provisioning with a valid configuration ultimately observes a tenant whose sending domain is verified for DKIM and Return-Path and is ready to send.
2. Per-tenant DKIM isolation is verifiable. Email sent on behalf of a tenant passes DKIM, SPF, and DMARC checks at the receiver, with signatures bound to that tenant’s sending sub-domain.
3. Sending and tracking are functional. A consumer that requests an email send observes the email transmitted, and the corresponding delivery, bounce, or complaint event from Postmark updates the recorded job status correctly.
4. Webhook traffic is authenticated. Postmark-emitted webhook requests reach the platform only via the Bearer-token-authenticated route; unauthenticated webhook attempts are rejected by the receiving component.
5. Server tokens are encrypted at rest. No tenant Postmark server token is persisted in plaintext anywhere in the stack.
6. Free Kanban Tool can send. The Free Kanban Tool, provisioned within the Corporate Resource Group, sends transactional email from freekanban.arda.ardamails.com with valid DKIM, SPF, and DMARC.
7. Drift detection is live. A scheduled drift check exercises the live Postmark surface and surfaces any divergence between declared and observed state via an automated GitHub issue.
8. External references resolve from CI. With the project’s required GitHub Actions secret in place, CI can resolve every Postmark and 1Password reference declared in the infrastructure repository at workflow runtime.
9. Operator-runbook documentation exists. A Postmark service overview and a Postmark-API observations note are available under the platform’s OAM documentation, sufficient for an operator to diagnose live behaviour and for a future implementor to understand the design intent without re-deriving it from third-party documentation.
10. Documentation is current. New pages for the services introduced by this project are in place, and existing documentation is reconciled with the practices and designs adopted in this project, covering at minimum current-system/runtime/, current-system/oam/, and current-system/architecture/.

Out of scope

• Frontend SPA components for email composition or status display.
• BFF route definitions for the email capability.
• Procurement-specific use cases (email orders, purchase order by email, order-submit integration).
• HTML email template rendering for specific business entities.
• Tenant self-service administration UI.
• Inbound email processing (procurement inbox, reply-to threading).
• Any Arda-built OAM surface for the email service. Day-to-day operational management is performed through the Postmark Console; this project consumes the Postmark Console as the operational tool, not augments or replaces it.
• Migration of pre-existing Arda operator scripts (amm.sh, deploy-root.sh) to the principle-aligned operator-script shape.
• Arda platform-level transactional email (operational notifications from the platform itself); anticipated as a future capability.

Deliverables

Concrete project outputs.

Deliverable	Repository	Description
Postmark accounts and 1Password items	external (Postmark, 1Password)	PostmarkProd and PostmarkNonProd accounts (Platform plan); account-level API tokens stored in Arda-SystemsOAM; service-account token for unattended CI access.
Platform-level external references	infrastructure	Typed reference declarations for all external resources consumed by the platform (Postmark accounts, 1Password vault items).
Corporate Resource Group (founding)	infrastructure	The Corporate Resource Group as a runtime instance group, with the arda.ardamails.com zone (SPF + DMARC), the Free Kanban Tool’s sending domain (freekanban.arda.ardamails.com) and Postmark server, and a dedicated operator CLI.
Per-partition mail infrastructure	infrastructure	A mail sub-zone, an encrypted-at-rest token store, an encryption key, and a DNS-provisioning IAM role for each Application Runtime partition.
Email-sending capability for Application Runtime tenants	operations, common-module	An API surface that consumers (SPA, BFF, others) call to provision tenants, send email, and observe delivery; webhook handling for Postmark events; supporting library additions consumed by the email module.
Drift-detection workflows	infrastructure	Scheduled GitHub Actions runs that exercise the live external surfaces, opening an issue on failure.
Postmark service documentation and API observations note	documentation	Operator overview at current-system/oam/postmark-service/. The API observations note at current-system/oam/postmark-service/postmark-api-observations.md records the Postmark API surface design intent: authentication models for both API and Webhooks, error model, idempotency conventions, retry policy, webhook payload shapes, and version-pin assumptions. Written so future implementors do not re-derive these.
Reserved-name registry update	infrastructure	The mail-zone reserved-name list updated to reflect the arda.ardamails.com separation, preventing future tenant-slug collisions at the ardamails.com level.
Ad-hoc GitHub Actions secret-provisioning utility	infrastructure	An operator CLI (tools/gha-secret.ts) that provisions a GitHub Actions secret from a 1Password reference, used during the transition before declarative GHA-secret management is in place.
New and reconciled platform documentation	documentation	New pages for the services introduced by this project (Postmark service, Corporate Resource Group operations, drift-detection conventions); reconciliation of existing pages in current-system/runtime/, current-system/oam/, and current-system/architecture/ with the practices and designs adopted in this project. Decision log and architectural scenarios kept current; current-system retrofit at project completion.

Key decisions

Each implementation constraint and architectural element above is anchored in a recorded decision. The full text lives in the project decision log. The decisions that bear directly on the project goal:

#	Topic	Project bearing
DQ-001	Tenant domain structure	Per-tenant sending-domain shape: {config-slug}.{tenant-slug}.{partition}.ardamails.com.
DQ-002	Multi-config strategy	A tenant may have multiple email configurations; each gets its own sub-sub-domain.
DQ-003	Tenant slug source	Slug derivation from the provisioning request inputs.
DQ-009	Mail root domain	Standalone ardamails.com, parametric throughout the implementation.
DQ-010	Partition zone placement	Each partition owns its mail sub-zone; the root zone is static.
DQ-011	Webhook authentication	Bearer token via Postmark’s modern Webhooks API.
DQ-012	Server token storage	Per-tenant tokens encrypted at rest with a per-partition key.
DQ-201 — DQ-208	Application-layer decisions	Internal partitioning of the email-sending implementation, encryption / key derivation, async DNS verification mechanism, and persist-first lifecycle.
DQ-R1-NNN	Revision-1 decisions	Establishment of the Corporate Resource Group as a runtime instance group; arda.ardamails.com topology and reserved-name discipline; AWS-account-vs-instance-group decoupling; declarative-by-default operator-script pattern; transition arrangements for Postmark-server creation.

Decisions not listed here (e.g., implementation-internal choices) are recorded in the decision log and do not affect goal-level outcomes.

Glossary

Concepts referenced in this document, with self-contained descriptions.

Term	Description
Application Runtime	One of Arda’s runtime instance groups: a deployment of the Arda product that serves end-users. An Application Runtime is itself composed of one or more Infrastructures, each containing one or more Partitions.
Infrastructure	A unit within an Application Runtime that hosts shared cloud resources (VPC, EKS cluster, parameter and secret stores). One Infrastructure may host multiple Partitions. Examples: Alpha001, Alpha002, SandboxKyle002.
Partition	A unit within an Infrastructure dedicated to a specific purpose. Examples: prod, dev, stage, demo, kyle. Each partition holds the resources tenants of that purpose access.
Tenant	An end-customer of an Arda product, holding configuration and resources within a Partition. Each tenant has at least one configuration that includes a sending domain for transactional email.
Corporate Resource Group	A runtime instance group, peer to the Application Runtime instance group, that holds Arda-owned assets used to operate the company’s information systems and customer-facing tooling. The project establishes this group with the Free Kanban Tool as its founding member.
Free Kanban Tool	An Arda-owned product (part of arda.cards) that allows visitors to compose Kanban cards. Sends transactional email from freekanban.arda.ardamails.com. The first consumer of the email capability within the Corporate Resource Group.
ardamails.com	The standalone DNS domain reserved for Arda’s transactional mail. Holds NS delegations to the Corporate Resource Group’s mail zone and to each Application Runtime partition’s mail sub-zone, plus root-level SPF and DMARC records.
arda.ardamails.com	The DNS zone used for Corporate-Resource-Group sending traffic. Holds SPF and DMARC records for Corporate consumers, and sub-domain records for individual Corporate sending domains (e.g., freekanban.arda.ardamails.com).
Sending domain	A DNS sub-domain dedicated to a tenant’s or consumer’s transactional email, with DKIM and Return-Path records that authenticate mail sent on its behalf.
Postmark account	A top-level identity in Postmark holding zero or more Postmark servers under a single Platform-plan billing entity. Arda owns two: PostmarkProd (production-bound) and PostmarkNonProd (development / sandbox).
Postmark server	A Postmark-side container for the configuration and credentials of one logical sender (one tenant or one Corporate consumer). Holds the Server API token used to send.
Postmark webhook	An HTTP callback that Postmark issues for delivery, bounce, and complaint events. Authenticated to Arda via a Bearer token validated in-component by the receiving route.
DKIM, SPF, DMARC	Email authentication standards. DKIM signs outgoing email with a per-domain key; SPF authorises a sender’s source IPs; DMARC enforces alignment of the two and instructs receivers on handling failures.
Drift detection	A periodic, scheduled assertion that the state of an external resource (e.g., a Postmark account or sending domain) matches the declarative description in the infrastructure repository. Failures trigger an automated investigation issue.
External Secrets Operator	A Kubernetes operator that synchronises secret material from a backing store (here, AWS Secrets Manager) into Kubernetes secrets accessible to pods, refreshed on a schedule.