Bump version to 0.2.0-SNAPSHOT [skip ci]

pom.xml: parent -> 2.2.1
pom.xml: qqq.snapshot.version: 4.1.0-RC.8 -> 4.1.0-RC.25
pom.xml: qqq-frontend-next: 1.0.0-RC.19 -> 1.0.0-RC.38

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.circleci/config.yml

@@ -1,65 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-  qqq-orb: kingsrook/qqq-orb@0.6.8
-
-commands:
-  configure-package-install:
-    steps:
-      - run:
-          name: Keep package installation unattended
-          command: |
-            # These build machines are discarded after the job.
-            sudo install -d /etc/needrestart/conf.d
-            printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.8
 workflows:
-
-  test_only:
+  setup:
     jobs:
-      - qqq-orb/mvn_test_only:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          filters:
-            branches:
-              ignore: /(develop|release/.*|integration.*)/
-            tags:
-              only: []  
-
-  publish_snapshot:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: snapshot
-          filters:
-            branches:
-              only:
-                - develop
-
-  publish_release_candidate:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: release_candidate
-          filters:
-            branches:
-              only:
-                - /release\/.*/
-
-  publish_release:
-    jobs:
-      - qqq-orb/mvn_publish:
-          pre-steps:
-            - configure-package-install
-          context: [ qqq-maven-registry-credentials ]
-          branch_type: release
-          filters:
-            branches:
-              ignore: /.*/
-            tags:
-              only: [ /^v\d+\.\d+\.\d+$/ ]
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.gitea/workflows/build.yaml

@@ -0,0 +1,7 @@
+name: build
+on:
+  push:
+jobs:
+  maven:
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
+    secrets: inherit

.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
 name: Release candidate
-
-on:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 jobs:
   release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: '0.8'
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release-no-integration
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

AGENTS.md

@@ -20,14 +20,19 @@ Design: `docs/DESIGN.md`.
 
 - **Entry point:** `EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>`, package `com.kingsrook.qbits.email`.
 - `metadata`: seven tables, enum sources, relations and provider/suppression validation.
-- `outbox`: EmailService, requests/results and the replaceable ad-hoc renderer.
+- `outbox`: EmailService, queue-time template rendering, protected resend and branded ad-hoc rendering.
 - `delivery`: durable dispatcher, attempt leases, rate limits, health and optional alerts.
 - `transport`: shared MIME, SMTP/SES transports, settings and registry.
 - `bridge`: QBIT_EMAIL adapter for core SendMessageAction.
 - `processes`: Review/Result record actions, backend send API and scheduled jobs.
 - `permissions`, `app`, `support`: custom permission checker, app/navigation and authorized database operations.
 - `EmailRuntime` resolves config from the current instance; `EmailIntegrations` declares ESB, API and Quick Search tables.
-- Templates/branding/PHI/full home rendering are part 2; their tables exist now.
+- `template`: parsed variable language/schema, locale resolution, immutable versions, version-bound PHI approval, MJML compilation, lazy secure-message built-in and inline preview.
+- `render`: CommonMark extensions, table-based light/dark layout, contrast validation, text conversion and unsubscribe-link signing (handler is phase c).
+- `phi`: RC.5 classification/token stand-ins and AES-GCM encryption; only dispatch decrypts bodies.
+- `app/EmailHome`: viewer-scoped counts and inline cards, with standard hourly/suppression chart widgets.
+- Version operations serialize on the template row; active/approved version selectors are parent-scoped.
+- Preview UI API endpoint awaits RC.6; webhook/unsubscribe handlers remain phase c.
 
 ## Invariants
 

CHANGELOG.md

@@ -6,6 +6,50 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 ## [Unreleased]
 
 ### Added
+- Shared-template APIs for permission- and record-lock-checked variable discovery, typed rendering, and idempotent sends with the exact stored subject and template/version provenance. Checked subject results bind replay to the same recipient, category, sender and linked record.
+- Optional host template read/write grants without granting provider, message, brand or PHI administration. Existing per-template edit permissions remain additional requirements.
+- `CRM_LEGACY` templates preserve migrated CRM token replacement, overrides and text-before-HTML behavior inside the email renderer. Native templates retain their existing category and content policies; migration and opt-in remain host responsibilities (see `UPGRADE.md`).
+
+### Changed
+- Built on QQQ 4.1.0-RC.8 (default QQQ profile).
+
+### Added
+- Central `email.provider.<id>` and `email.readiness` health checks (DEPENDENCY, EMAIL, 300 seconds), using passive provider state and existing category readiness with deadline and secret-safety coverage. Standard Email health status widget links to central checks. Uses the QQQ 4.1.0-RC.8 health API.
+- Foreign keys between all ten tables in `docs/ddl/email-postgres.sql`, named `fk_<table>_<column>`. CASCADE: a provider's sender addresses and a message's attempts and events. RESTRICT: providers with messages, attempts, events or webhook inbox rows; a brand used by a template; a template with versions. SET NULL: a message's sender address, template, version and brand; a template's active and approved version (the template/version cycle); a suppression's source message and event, so suppressions survive message retention. Ten new indexes cover the unindexed key columns. `docs/ddl/email-foreign-keys-upgrade.sql` adds the keys to an existing database. It first records orphan rows in `qqq_fk_quarantine`: nullable references are set to NULL, and rows whose required parent is missing are deleted and kept as JSON. The script is idempotent. The provider delete check now also refuses providers with attempts, events or inbox rows. `ForeignKeyGuardrailTest` (PostgreSQL 17 via Testcontainers) fails when a join or table possible-value field between email tables has no foreign key.
+- Starter defaults changelog `db/liquibase/qbit-email/email-defaults.changelog.sql` (insert-only, guarded): one non-default, high-contrast `neutral` brand, only when no brand exists. Tested through real Liquibase on H2, including that it never changes rendering.
+- Host-neutral in-app help bundle for the Email app, tables, fields, actions and widgets, registered through QQQ's help bundle API. Replaces the temporary inline loader, preserves record-creation explanations and supports HOST overrides. The coverage gate checks owned metadata, summaries and live references.
+- A Setup card first on the Email home (email admins), using the sender's own provider and brand resolution and `EmailApi.readiness`. Opening the home also creates the built-in secure-message template.
+- `EmailTablesGuardrailTest`: every table is used by runtime code, seeded or listed as starting empty with a reason, and has help.
+
+### Fixed
+- The `email.readiness` health message now names each missing item in plain words and where to set it (for example "Brand postal address is not set (Email > Brand > open the default brand > Postal address)") and says transactional email is unaffected by marketing-only gaps. The `failedChecks` detail is unchanged; a new `howToFix` detail lists the same text.
+- Derive the qbit metadata version from the Maven artifact version so released artifacts report their release version.
+- `email_template.ownerQbit` was stored but never read, and the built-in template did not set it. The built-in now names `qbit-email`, the field is read-only with help, and messages sent from a template name its owner qbit as `senderQbit` unless the request names one.
+
+### Added
+- `EmailJobEffectTarget` automatically registers the durable-jobs `email` target, with idempotent outbox handoff, refusal reasons, reconciliation and job-owner session enforcement; H2 integration coverage and payload/registration documentation.
+- `EmailApiReadiness.failedChecks()` and `failed(check)` with `EmailApiReadinessCheck` (NOT_INSTALLED, PROVIDER_MISSING, PROVIDER_INVALID, PHI_PROVIDER, PUBLIC_BASE_URL, UNSUBSCRIBE_KEY, BRAND_POSTAL_ADDRESS, BODY_KEY), so callers react to a specific prerequisite without parsing reason text.
+- `EmailApi.sendOnce` as the public durable-effect handoff, with API-only outcome/result types, committed enqueue/replay semantics and suppression/transaction refusal parity. Exact idempotency-key and RFC Message-ID lookups return `EmailApiMessage`, which now includes `rfcMessageId` across all lookup routes. Public requests support ordinary caller transactions; `EmailEffects`, `EmailEffectOutcome` and `EmailMessageRef` are deprecated internals. H2 parity, reconciliation, storage-failure and API-boundary coverage; no new dependencies.
+- Stable `com.kingsrook.qbits.email.api` contract for cross-qbit sends, create-once templates, metadata-only message lookups, enabled sender addresses, default provider selection and secret-safe readiness (including marketing and PHI prerequisites). JDK/QQQ-only signatures, complete request/status mapping tests and a reflection package-boundary guard; no new dependencies.
+- Documented both supported cross-qbit routes: core-only `SendMessageAction` via `qbitEmail`, and the public API for richer sends and lookups.
+- Persisted unique RFC Message-IDs, stable across delivery attempts, with SMTP/Gmail SMTP, SES raw MIME and Postmark/SendGrid/Mailgun request propagation (SES replaces the header downstream).
+- Core-independent `EmailEffects` handoff, reference lookups by idempotency key or RFC Message-ID and refusal mapping; offline retry and provider-contract tests.
+- Checkstyle now checks test sources as well as main sources; existing test imports and formatting corrected.
+- Provider sender addresses: child table `email_provider_sender_address` (validated lowercase address, display name, one default, enabled, note; unique per provider; domain bound to the provider's sending domain; admin-only), shown on the provider record. `EmailRequest.withFromAddressId`, `from_address_id` on messages, refusal of a from address that is not an enabled row of the resolved provider, and the provider `from_address` / `from_name` kept as the fallback.
+- Contingent possible-value filters on the new from-address pickers (send processes by `providerId`, Send Test Email by the acted-on provider, message `fromAddressId` by `providerId`) and on the attempt and event message pickers (by `providerId`) and the suppression source event (by `sourceMessageId`); the send processes also take `providerId`.
+- Phase (c): authenticated SNS, Postmark, SendGrid and Mailgun webhooks, durable inbox deduplication and Mailgun nonce replay protection; configurable Javalin routes.
+- Atomic scheduled event processing, per-recipient event history, monotonic delivery state, category-aware suppression, optional daily complaint alerts and FAILED inbox Reprocess with Review/Result.
+- One-click unsubscribe and escaped self-contained light/dark confirmation pages using the existing envelope-bound signer; account/security tokens refused.
+- Event-based home totals, PostgreSQL/H2 tracking DDL, provider setup instructions, test-only SNS certificate/key and real HTTP, crypto, parser, concurrency, retry and privacy tests. Preferences stays deferred until core #1162 reaches an RC.
+- Phase (a), part 2: versioned Markdown/HTML/MJML templates, typed variable schemas, escaped blocks/loops/fallbacks, branded light/dark layout and contrast validation.
+- New Version, Activate Version and version-bound Approve For PHI actions, edit permissions, immutable history and parent-scoped version selectors.
+- Sender-scoped record variables, classification stand-in, HMAC snapshot tokens, AES-GCM bodies, encrypted query displays and protected resend.
+- Lazy secure-message built-in, typed templated core bridge, process JSON variables, inline preview and viewer-scoped dashboard charts/cards.
+- PHI canary egress, masking, lifecycle, parent-filter, rendering, branding and GreenMail template tests.
+
+- Phase (b) Postmark, SendGrid and Mailgun HTTP transports with fixed HTTPS endpoints, bounded requests, tracking options, safe error classification and Retry-After support; no new dependencies or filesystem storage.
+- Strict Gmail SMTP credential/STARTTLS validation, provider-specific credential and webhook environment defaults, and the [provider setup guide](docs/PROVIDERS.md).
+- HTTP request-contract tests and local-server end-to-end outbox tests covering success, provider failures, permanent rejection, retries and secret-safe stored errors.
 - Phase (a), part 1 email tables, PostgreSQL DDL, enum sources, child relations, permissions and Email app navigation.
 - Provider validation with environment-name allowlists and presence-only credential displays.
 - Transactional ad-hoc EmailService, idempotency, suppression and a replaceable Markdown/HTML/text renderer.
@@ -14,3 +58,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 - QBIT_EMAIL core messaging bridge, Review/Result actions, backend send process, dispatch/maintenance/retention schedules and host integration declarations.
 - H2 concurrency and transaction tests, GreenMail end-to-end tests, fake SES tests, metadata/permission checks and process-runner coverage.
 - Repository scaffold to the QRun qbit repository standard (Apache-2.0, CircleCI qqq-orb 0.6.8 with the `configure-package-install` pre-step, GA-only `publish_release`, the `release-rc` caller workflow).
+
+### Removed
+- The Email home's standalone Provider health listing, including per-provider failure messages, last-success details and rate-headroom queries. Passive delivery health and `email.provider.unhealthy` alerts are retained.

CLAUDE.md

@@ -20,14 +20,19 @@ Design: `docs/DESIGN.md`.
 
 - **Entry point:** `EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>`, package `com.kingsrook.qbits.email`.
 - `metadata`: seven tables, enum sources, relations and provider/suppression validation.
-- `outbox`: EmailService, requests/results and the replaceable ad-hoc renderer.
+- `outbox`: EmailService, queue-time template rendering, protected resend and branded ad-hoc rendering.
 - `delivery`: durable dispatcher, attempt leases, rate limits, health and optional alerts.
 - `transport`: shared MIME, SMTP/SES transports, settings and registry.
 - `bridge`: QBIT_EMAIL adapter for core SendMessageAction.
 - `processes`: Review/Result record actions, backend send API and scheduled jobs.
 - `permissions`, `app`, `support`: custom permission checker, app/navigation and authorized database operations.
 - `EmailRuntime` resolves config from the current instance; `EmailIntegrations` declares ESB, API and Quick Search tables.
-- Templates/branding/PHI/full home rendering are part 2; their tables exist now.
+- `template`: parsed variable language/schema, locale resolution, immutable versions, version-bound PHI approval, MJML compilation, lazy secure-message built-in and inline preview.
+- `render`: CommonMark extensions, table-based light/dark layout, contrast validation, text conversion and unsubscribe-link signing (handler is phase c).
+- `phi`: RC.5 classification/token stand-ins and AES-GCM encryption; only dispatch decrypts bodies.
+- `app/EmailHome`: viewer-scoped counts and inline cards, with standard hourly/suppression chart widgets.
+- Version operations serialize on the template row; active/approved version selectors are parent-scoped.
+- Preview UI API endpoint awaits RC.6; webhook/unsubscribe handlers remain phase c.
 
 ## Invariants
 

README.md

@@ -1,20 +1,20 @@
 # QBit Email
 
-Phase (a), part 1: a durable email outbox for QQQ, with SMTP and Amazon SES transports,
-suppression, retries, provider health, record actions, and the core messaging bridge.
-Every send is queued in `email_message` before a dispatcher contacts a provider.
+One email service for a QQQ system: a durable outbox (`email_message`) with retries, dead
+letters, idempotency keys, rate limits and provider health; SMTP, Amazon SES, Postmark,
+SendGrid, Mailgun and Gmail SMTP transports; versioned Markdown, HTML and MJML templates with
+dark-mode-safe branding; classified variables and PHI protection; preview widgets; a
+real-data home; delivery events, suppression and one-click unsubscribe; and the core messaging bridge. Every send goes through the outbox.
 
-The approved [design](docs/DESIGN.md) covers later phases too. This implementation
-accepts ad-hoc Markdown, HTML and text. Template rendering, branding, PHI handling and
-the full home dashboard belong to part 2. Template and variable-bearing requests are
-refused in part 1; attachments are refused. Tracking webhooks, unsubscribe and the
-additional HTTP transports remain later phases.
+The [design](docs/DESIGN.md) also specifies the deferred Preferences UI (core #1162),
+consumer migrations and inbound mail. Preview uses the standard widget endpoint; the
+dedicated preview API arrives with QQQ RC.6. Attachments are refused until
+qbit-object-storage is wired in.
 
 ## Install
 
-Requires Java 21, QQQ **4.1.0-RC.5**, and a transactional RDBMS with the supplied unique
-constraints. Apply [the PostgreSQL DDL](docs/ddl/email-postgres.sql) before producing
-the qbit. SQL timestamps store UTC values without a timezone, matching QQQ RC.5.
+Requires Java 21, QQQ **4.1.0-RC.8**, and a transactional RDBMS with the supplied unique
+constraints. Apply [the PostgreSQL DDL](docs/ddl/email-postgres.sql) before producing the qbit. SQL timestamps store UTC values without a timezone, matching QQQ RC.5.
 The physical table names equal their metadata names; `backendName` selects the host's
 QQQ database backend, as it does in qbit-webhooks.
 
@@ -39,17 +39,44 @@ The scheduler must already exist. Without a scheduler, callers can enqueue and r
 Configuration is looked up from the current `QInstance` on every call, never cached
 in a static variable.
 
+## Starter defaults and setup
+
+Include order: the DDL first, then the starter defaults from the host's master changelog (the qbit itself never runs DDL):
+
+```yaml
+- include: { file: db/liquibase/qbit-email/email-defaults.changelog.sql }
+```
+
+They are insert-only, hold no secrets, skip a host without the tables, and never change how mail looks on deploy. They add one brand, `neutral` (white background, near-black text, blue buttons, light and dark schemes, every pair at least 4.5:1 contrast), and only when the host has no brand at all. It is not the default brand: copy it for your own, or tick Default Brand on it.
+
+Everything else starts empty on purpose, and each table's help says why: a **provider** is your own connection (a server and the NAMES of its secret variables), so nothing can be sent until you add one; messages, attempts, events, the webhook inbox and suppressions are runtime data; the secure-message template is created by the qbit on first use and when the Email home opens, and other qbits register theirs with `EmailApi.ensureTemplate`.
+
+Every table has help that says what it is for and **how its rows get created**, available through the host's help bundle sync. Email admins also get a **Setup** card first on the home: provider, sender addresses, brands, templates, marketing readiness, delivery tracking, suppression list and scheduler, each with its state and the next step. It uses the same provider and brand resolution as the sender and `EmailApi.readiness`.
+
+### In-app help
+
+The producer registers [help/qbit-email.yaml](src/main/resources/help/qbit-email.yaml) as a `QBIT` bundle using QQQ's help bundle API. Registration is metadata-only and works without a `helpContent` table; hosts with help enabled load and sync registered bundles through QQQ. The app entry follows `EmailQBitConfig.appName`.
+
+To override wording or add deployment-specific instructions, register a separate `layer: HOST` bundle with the same entry keys and roles using `HelpBundles.register(qInstance, "help/your-host.yaml")`. HOST entries take precedence over QBIT entries; UI edits remain protected by the core sync. Keep the bundle version aligned with the POM's artifact version when releasing.
+
+`EmailTablesGuardrailTest.everyTableHasEmptyStateHelp` runs `HelpBundleAssertions` against the produced instance to check owned objects, non-trivial fields, summaries and live references, with no exclusions. `EmailQBitProducerTest` checks registration without a help table and with a custom app name. Both run during `./mvnw verify`.
+
+A template's **Owner Qbit** (the qbit that registered it) is now used: messages sent from the template name that qbit as their sender unless the request names one.
+
 ## Tables and permissions
 
 | Table | Navigation | Writes |
 |---|---|---|
 | `email_message` | Messages | Qbit only; people use record actions |
 | `email_message_attempt` | Attempts on a message | Qbit only |
-| `email_template` | Templates | `email.manage`; rendering arrives in part 2 |
-| `email_template_version` | Versions on a template | `email.manage`; activation arrives in part 2 |
-| `email_brand` | Brands | `email.manage`; rendering arrives in part 2 |
+| `email_event` | Events on a message | Qbit only; readable with `email.view` |
+| `email_webhook_inbox` | Inbox on a provider | Qbit only; readable with `email.view`; Reprocess requires `email.manage` |
+| `email_template` | Templates | `email.manage`; template edit grants also apply |
+| `email_template_version` | Versions on a template | Draft edits only; lifecycle uses record actions |
+| `email_brand` | Brands | `email.manage`; template edit grants also apply |
 | `email_suppression` | Suppressions | `email.manage`; changing/removing a complaint needs `email.admin` |
 | `email_provider` | Providers, with child Messages | `email.admin`, including reads and test sends |
+| `email_provider_sender_address` | Sender Addresses on a provider | `email.admin`, including reads |
 
 `email.view` reads messages, templates, versions, brands and suppressions.
 `email.send` permits the Java service, bridge and backend send process. Reading
@@ -67,11 +94,48 @@ insert/update/delete capabilities. Labels contain no status decorations.
 
 ## Providers and credentials
 
+See the [provider setup guide](docs/PROVIDERS.md) for row fields, DNS/domain setup,
+limits, Gmail app passwords and provider webhook setup.
+
+| Kind | Transport | Status |
+|---|---|---|
+| SMTP | Relay or authenticated SMTP, STARTTLS / TLS | Available |
+| SES | AWS SES v2, raw MIME | Available |
+| POSTMARK | HTTPS JSON, server token and message stream | Available |
+| SENDGRID | HTTPS JSON, bearer API key | Available |
+| MAILGUN | HTTPS MIME multipart, US / EU | Available |
+| GMAIL_SMTP | smtp.gmail.com:587, STARTTLS and app password | Available |
+| GMAIL_API | OAuth Gmail API | Deferred; use GMAIL_SMTP |
+
 Create the first enabled provider with `isDefault=true`. When any providers are
 enabled, exactly one must be the enabled default. Switch defaults in a batch update,
 clearing the old default first. A nullable unique `default_slot` backs the validation.
 Providers with message history cannot be deleted; disable them instead.
 
+**Sender addresses.** A provider can own any number of verified from addresses, kept in
+`email_provider_sender_address` and shown as a Sender Addresses list on the provider record
+(not in the nav; `email.admin` reads and writes, like the provider). Each row has an
+`address` (validated, stored lowercase, line breaks refused), an optional `displayName`,
+`isDefault`, `enabled` and a `note`. An address is unique per provider, at most one enabled
+row per provider is the default, and when the provider has a `sendingDomain` every address must
+be in that domain (changing the domain with other-domain rows is refused). Deleting a provider
+deletes its rows. Existing databases add the table and the nullable
+`email_message.from_address_id` column from `docs/ddl/email-postgres.sql`.
+
+The provider's own `fromAddress` / `fromName` stay the fallback, so nothing changes until a
+row exists. A row marked default wins over the fallback. On a send, `withFromAddressId(id)`
+(or `fromAddressId` on the send processes) must name an enabled row of the resolved provider,
+and once a provider has rows an explicit `withFrom(...)` must match one of them by address;
+either failure is `REFUSED` with "That from address is not set up for provider <name>". With
+no rows, `withFrom(...)` behaves as before. The chosen row is recorded on the message as
+`fromAddressId`, and a resend reuses it.
+
+The from address pickers are contingent: `fromAddressId` on the send processes lists only the
+rows of the chosen `providerId` (`providerName` is still accepted for API callers, and the two
+must agree), and the Send Test Email action lists only the rows of the provider being tested.
+That action's form has no record id, so a prepare step publishes the single selected provider id
+as the process value `possibleValueFilterValueId`, which the picker's filter reads after `${input.id}`.
+
 For an unauthenticated relay, use kind `SMTP`, host/port, security `NONE`, and a
 `fromAddress`. Leave credential names empty. Authenticated SMTP uses `usernameEnvName`
 and `secretEnvName`; security is `NONE`, `STARTTLS` (required) or `TLS`. Timeouts are
@@ -91,11 +155,11 @@ for the selected kind:
 
 | Kind | Default allowed names |
 |---|---|
-| SMTP / GMAIL_SMTP | `EMAIL_SMTP_USERNAME`, `EMAIL_SMTP_PASSWORD`, `EMAIL_GMAIL_USERNAME`, `EMAIL_GMAIL_APP_PASSWORD` |
+| SMTP / GMAIL_SMTP | `EMAIL_SMTP_USERNAME`, `EMAIL_SMTP_PASSWORD`, `EMAIL_GMAIL_USERNAME`, `EMAIL_GMAIL_APP_PASSWORD`, `GMAIL_USERNAME`, `GMAIL_APP_PASSWORD` |
 | SES | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` |
-| POSTMARK | `EMAIL_POSTMARK_SERVER_TOKEN`, `EMAIL_POSTMARK_WEBHOOK_PASSWORD` |
-| SENDGRID | `EMAIL_SENDGRID_API_KEY`, `EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY` |
-| MAILGUN | `EMAIL_MAILGUN_API_KEY`, `EMAIL_MAILGUN_SIGNING_KEY` |
+| POSTMARK | `POSTMARK_SERVER_TOKEN`, `POSTMARK_WEBHOOK_PASSWORD`; legacy `EMAIL_POSTMARK_SERVER_TOKEN`, `EMAIL_POSTMARK_WEBHOOK_PASSWORD` |
+| SENDGRID | `SENDGRID_API_KEY`, `SENDGRID_WEBHOOK_PUBLIC_KEY`; legacy `EMAIL_SENDGRID_API_KEY`, `EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY` |
+| MAILGUN | `MAILGUN_API_KEY`, `MAILGUN_WEBHOOK_SIGNING_KEY`; legacy `EMAIL_MAILGUN_API_KEY`, `EMAIL_MAILGUN_SIGNING_KEY` |
 | GMAIL_API | `EMAIL_GMAIL_CLIENT_ID`, `EMAIL_GMAIL_CLIENT_SECRET`, `EMAIL_GMAIL_REFRESH_TOKEN` |
 
 Allowlisting does not automatically select a name. Empty SMTP references mean no auth;
@@ -106,10 +170,135 @@ resolved during an attempt and never retained, audited, returned or logged. The
 provider record's display-only fields return only `Set` / `Not set`; checking presence
 necessarily invokes the resolver too. Enqueue and internal queries do not resolve it.
 
-POSTMARK, SENDGRID, MAILGUN and GMAIL_API have metadata but no transport in this part.
-Their delivery attempts fail permanently with `not available until phase (b)`.
+POSTMARK, SENDGRID and MAILGUN require a secret environment name. Mailgun also
+requires a sending domain and US/EU region. Gmail SMTP requires both credential
+names and STARTTLS. GMAIL_API is refused with
+`Gmail API sending is specified but not built; use GMAIL_SMTP`.
 
-## Sending
+HTTP transports use fixed HTTPS endpoints, 10-second connect and 30-second request
+timeouts, and no redirects. HTTP 429/5xx retry with optional Retry-After; account
+and credential failures pause the provider. Tracking is explicitly controlled by
+`trackOpens` / `trackClicks`, off by default. The producer registers the phase-(c)
+receiver idempotently when the provided Javalin middleware is present.
+
+## Health checks
+
+The producer registers these checks with QQQ central health monitoring:
+
+| Name | Kind | Interval |
+|---|---|---|
+| `email.provider.<id>` (each enabled provider) | DEPENDENCY | 300 seconds |
+| `email.readiness` | DEPENDENCY | 300 seconds |
+
+Both use component `email`, category `EMAIL`, and a 5-second timeout. Provider
+checks read passive delivery state only: HEALTHY maps to UP, UNHEALTHY to DOWN,
+and missing/disabled/unknown state to UNKNOWN. The transport SPI has no
+non-sending connectivity method; these checks never contact providers or send
+mail. Readiness reuses `EmailApi.readiness` for every `EmailApiCategory`; any
+unmet prerequisite is DEGRADED, with only enum names in `failedChecks`. Existing
+passive state and `email.provider.unhealthy` alerts remain in place.
+
+The Email home uses a standard status widget reading the central `health_component`
+rollup, with a link to System Health's checks filtered to `email`. It no longer
+lists provider diagnostics. The host must install central health metadata and its
+schema; central reads use the viewer's health permissions.
+
+This integration uses the core health API released in QQQ `4.1.0-RC.8`.
+Verify offline with `./mvnw -o verify` (`mvnw.cmd` on Windows).
+
+## Sending from another qbit
+
+There are two supported routes. Both queue through the durable outbox; a successful
+call acknowledges enqueueing, not delivery.
+
+**1. QQQ core only, for simple subject/body email.** The host installs qbit-email;
+the consuming qbit needs no qbit-email dependency or imports. Use
+`SendMessageAction` with `messagingProviderName` set to `qbitEmail` (the default
+bridge name; hosts can configure another name):
+
+```java
+import com.kingsrook.qqq.backend.core.actions.messaging.SendMessageAction;
+import com.kingsrook.qqq.backend.core.model.actions.messaging.Content;
+import com.kingsrook.qqq.backend.core.model.actions.messaging.Party;
+import com.kingsrook.qqq.backend.core.model.actions.messaging.SendMessageInput;
+import com.kingsrook.qqq.backend.core.model.actions.messaging.email.EmailContentRole;
+
+new SendMessageAction().execute(new SendMessageInput()
+   .withMessagingProviderName("qbitEmail")
+   .withTo(new Party().withAddress("pat@example.com"))
+   .withSubject("Ready")
+   .withContent(new Content().withContentRole(EmailContentRole.TEXT).withBody("Your export is ready.")));
+```
+
+**2. The published `com.kingsrook.qbits.email.api` package**, for templates,
+idempotency, categories, linked records, sender selection and delivery lookups.
+Consumers with a qbit-email dependency import only this package:
+
+```java
+import com.kingsrook.qbits.email.api.EmailApi;
+import com.kingsrook.qbits.email.api.EmailApiRequest;
+import com.kingsrook.qbits.email.api.EmailApiResult;
+
+EmailApiResult result = EmailApi.send(new EmailApiRequest()
+   .withTo("pat@example.com")
+   .withTemplateName("order_ready")
+   .withVariable("order_number", "A-1")
+   .withVariable("customer_name", "Pat")
+   .withIdempotencyKey("orders:42:ready")
+   .withLinkedRecord("orders", 42)
+   .withSender("orders", "ready"));
+```
+
+`EmailApi.ensureTemplate(EmailApiTemplate)` creates a template once; see
+[Templates from another qbit](#templates-from-another-qbit).
+
+For durable job effects, use `EmailApi.sendOnce(request, effectKey)`. It assigns
+the effect key as the request's idempotency key and returns `EmailApiEffectResult`
+with `EmailApiEffectOutcome.QUEUED_OR_DUPLICATE` or `REFUSED` and a nullable
+`EmailApiMessage`. Success means the outbox has committed; duplicate handoffs return
+the same row and RFC Message-ID. Null requests, null/blank/over-500-character keys,
+conflicting request keys and caller transactions are refused. Suppressed rows remain
+refused on replay and include their audit metadata; refusals without a row have no
+message. Database failures throw `QException` for retry or reconciliation. Ordinary
+`EmailApi.send` accepts `request.withTransaction(transaction, backendName)` when a
+caller-owned or cross-backend deferred enqueue is needed. See [durable job effects](docs/DURABLE-JOBS.md).
+
+`EmailApi.isInstalled(instance)` detects whether the qbit was produced.
+`defaultProviderName(instance)` resolves an enabled configured/default provider;
+`listSenderAddresses(providerName)` lists enabled sender rows (null selects the
+default). `readiness(instance, category)` reports configuration prerequisites,
+including MARKETING's public URL, unsubscribe key and default brand postal address.
+For a PHI-approved template, use `readiness(instance, category, true)` to also check
+the body key and provider PHI/tracking policy. PHI is a template approval state,
+not a category. Readiness is a preflight, not proof that a particular send will pass.
+
+`getMessage(id)`, `getMessageByIdempotencyKey(key)`, `getMessageByRfcMessageId(rfcMessageId)`
+and `findMessagesByIdempotencyKeyPrefix(prefix, limit)` expose only
+id, delivery status, category, idempotency key, RFC Message-ID, provider message id, template name,
+linked table/id and create/sent/delivered timestamps. They never return addresses,
+subjects, bodies or variable snapshots. Prefixes are literal and nonblank; limits
+must be positive; results are ordered by ascending message id. Missing messages
+return an empty Optional/list. Exact-key lookups also return empty for null/blank
+values; RFC lookup takes the stored bracketed header, not a provider response id.
+Ordinary enqueue results have `QUEUED`, `DUPLICATE`,
+`SUPPRESSED` or `REFUSED`; delivery status is a separate string on `EmailApiMessage`.
+
+Database calls require the caller's initialized `QContext`; methods accepting an
+installed instance require it to be the current context instance. Lookups run as
+the email system, so callers must authorize any exposure to their own users.
+Sending retains the existing permission, schema, PHI, suppression and recipient
+rules. Database failures propagate as core `QException`; invalid template definitions
+and lookup arguments throw `IllegalArgumentException`. No secret values are exposed.
+
+The API uses only JDK, QQQ core and its own API types in published signatures.
+Changes within a `0.x` minor release line are additive only. Internal packages
+(including runtime, configuration, outbox, metadata, support and template classes)
+are not API and may change. `EmailEffects`, `EmailEffectOutcome` and `EmailMessageRef`
+are deprecated internals; `EmailApi` is the sole public qbit-email surface.
+The internal service details below describe host and
+qbit-email implementation behavior, not additional cross-qbit contracts.
+
+## Internal sending service
 
 ```java
 EmailSendResult result = EmailService.send(new EmailRequest()
@@ -127,8 +316,8 @@ Use `withHtmlBody` or `withTextBody` instead of Markdown, with optional explicit
 alongside HTML. `withFrom`, `withReplyTo`, `withBcc`, `withProviderName`, `withSendAfter`,
 and `withLocale` are supported. `sendingDomain`, when present, must match the sender's
 domain. Addresses are parsed strictly; header newlines are refused. Markdown raw HTML
-and unsafe URL schemes are disabled. `EmailRenderer` is the replacement seam for
-part 2. Both alternatives are stored at enqueue time and reused on retries.
+and unsafe URL schemes are disabled. Templates always use the validated template renderer. The ad-hoc renderer extension
+remains compatible. Both alternatives are stored at enqueue time and reused on retries.
 
 Results expose `messageId()`, `status()` (`QUEUED`, `DUPLICATE`, `SUPPRESSED`, `REFUSED`)
 and `reasons()`. Idempotency is global within the outbox. A repeated key returns the
@@ -154,6 +343,151 @@ to NOTIFICATION and MARKETING. Expired rows are ignored. Partial suppression dro
 only matching recipients and records them in `suppressedAddresses`; all-suppressed
 messages remain visible with SUPPRESSED status and never consume an attempt.
 
+## Templates, variables and branding
+
+Create an `email_template`, then use **New Version** to copy the active or latest
+version into a DRAFT. Edit its source, schema and synthetic sample values. **Activate
+Version** validates syntax, samples, classifications, brand contrast and optional
+MJML compilation, then retires the previous active version for that locale in one
+transaction. ACTIVE and RETIRED versions are immutable. Template-specific
+`editPermissionName` applies to CRUD and actions, in addition to the email permission;
+even email administrators need that explicit grant. Trusted system writes may bypass it.
+
+```java
+EmailService.send(new EmailRequest()
+   .withTemplateName("order_ready")
+   .withTo("pat@example.com")
+   .withRecordVariable("order", "order", 123)
+   .withVariable("count", 3)
+   .withLocale("en"));
+```
+
+A schema is a JSON list, for example:
+
+```json
+[
+  {"name":"order","label":"Order","type":"RECORD","required":true},
+  {"name":"count","label":"Items","type":"NUMBER","required":true},
+  {"name":"link","type":"URL","classification":"PUBLIC"}
+]
+```
+
+Types are STRING, NUMBER, DATE, DATE_TIME, BOOLEAN, URL, LIST and RECORD. Optional
+`table`/`field` bind a variable's classification to metadata. URL values must be
+absolute HTTP(S) URLs. Use `{{name}}`, `{{order.number}}`, `{{name|fallback text}}`,
+`{{#if count}}...{{/if}}`, and `{{#each items}}{{@index}}: {{this.name}}{{/each}}`.
+`this` also supports scalar list elements. Empty/null/false/zero values are false.
+Unknown variables, unsupported helpers, unclosed expressions and mismatched blocks
+produce line-numbered errors. Records and lists allow dynamic child paths; declare
+specific dotted entries when child types/requiredness matter. There is no raw output.
+HTML values are escaped; Markdown values cannot inject Markdown syntax. Subject and
+text contexts use plain values, with subject newlines refused.
+
+Built-ins are `brand.*` (snake_case names such as `label`, `site_url`, `primary_color`),
+`message.id` (the actual outbox primary key), `now` (UTC), and `unsubscribe_url`.
+The latter is empty for TRANSACTIONAL/SECURITY and when no notification opt-out key
+is configured. The requested locale resolves to an ACTIVE version, falling back to
+`en`. The template supplies the category unless the request overrides it.
+
+Brand precedence is request name, template brand, the configured app's brand,
+default brand, then the built-in neutral brand. Markdown uses CommonMark tables and
+autolinks; raw HTML is escaped. `[Label](https://example.com){.button}` creates a table
+button. The 600px shell includes preheader, logo variants, footer, social links and
+light/dark colors; marketing requires a postal address. Brand saves and activation
+require 4.5:1 text and button contrast in both modes. Optional `darkPrimaryColor` and
+`darkButtonTextColor` fall back to their light counterparts. Colors use `#RRGGBB`.
+
+HTML versions retain authored HTML, with escaped variables and an opt-out footer
+before `</body>`. For MJML configure `withMjmlCompiler(new CliMjmlCompiler(binaryPath))`
+or another compiler implementation. Compilation uses stdin/stdout only, with a
+20-second timeout; the stored `compiledHtml` is reused for sends. No runtime files,
+source files or compiler temp files are written by this qbit.
+
+The record Preview widget uses synthetic `sampleVariables`, sanitized inline light
+(390px maximum) and dark (600px maximum) samples plus wrapping plain text. Next's
+sanitizer removes iframes and style blocks, so this preview is not an exact mail-client
+emulator. Draft MJML is compiled in memory for preview when a compiler is configured;
+preview never stores the result or changes the version.
+
+### Templates from another qbit
+
+A qbit that sends its own mail ships the template with its code instead of asking an
+administrator to create it. Describe it with `EmailApiTemplate` and call
+`EmailApi.ensureTemplate` at startup or before first use:
+
+```java
+boolean created = EmailApi.ensureTemplate(new EmailApiTemplate()
+   .withName("order_ready")
+   .withLabel("Order ready")
+   .withCategory(EmailApiCategory.TRANSACTIONAL)
+   .withSubject("Order {{order_number}} is ready")
+   .withBody("Hi {{customer_name}}, order {{order_number}} is ready for pickup.")
+   .withVariable("order_number", "Order number", "STRING", true, "PUBLIC")
+   .withVariable("customer_name", "Customer name", "STRING", true, null)
+   .withSampleVariables("{\"order_number\":\"A-1\",\"customer_name\":\"Pat\"}")
+   .withOwnerQbit("orders")
+   .withEditPermissionName("orders.edit"));
+```
+
+`kind` defaults to MARKDOWN (MJML and HTML are also accepted), `withTextBody` is
+optional, and `withVariablesSchema(json)` replaces `withVariable` when you already have
+the JSON. When no template of that name exists, `ensureTemplate` validates the definition like
+Activate Version (syntax, schema, a render with the samples, MJML compile), creates the
+template and an ACTIVE version 1 as the qbit, and returns true. When one exists it does
+nothing and returns false, so people's edits and later versions are never overwritten;
+the unique name settles concurrent callers. An invalid definition throws
+`IllegalArgumentException` with plain reasons and writes nothing.
+
+## PHI and PII
+
+`withRecordVariable` reads through `QueryAction` in the sender's QContext; it does not
+open an authorized scope. Core password masking is preserved. RC.5 does not enforce
+ordinary `FieldSecurityLock` during QueryAction, so the email record loader also
+applies the field lock against the sender's security keys before copying any values.
+Classification precedence is reflective core `AiDataClassifications.ofField`, config
+`classificationOverrides`, schema declaration, then PUBLIC.
+
+PII/PHI variables require **Approve For PHI** (`email.admin`) on the exact version.
+Approval records actor/date and `approvedVersionId`; it freezes an approved draft.
+A new sensitive version must be approved before activation. Activating a version
+without its own approval clears the template's old approval. Approval of one locale
+version does not approve another locale. PHI-approved templates cannot be MARKETING,
+use provider open/click tracking, or use a provider without `phiAllowed`. Provider
+attestation and tracking are checked again immediately before dispatch.
+
+`email_secure_message` is created transactionally on its first send. It needs only
+a required URL variable `link` and brand built-ins; use it to send a sign-in link
+without putting patient data into email.
+
+PII/PHI snapshot values become `hmac:v1:<keyId>:<base64url>`, or `changed:v1` without
+a valid base64 `QQQ_AUDIT_HMAC_KEY`. Record tokens bind table, field and primary key;
+context tokens bind `email`, template name, variable name and message id. Context
+booleans and values with fewer than four distinct characters always use `changed:v1`.
+`shred:v1` is reserved for future core wipe-rule record fields and is never produced
+for context values. The classification and token helpers are explicit RC.7 stand-ins.
+
+PHI-approved subjects and HTML/text bodies are AES-256-GCM encrypted as
+`enc:v1:<base64url(iv|ciphertext|tag)>`, using SHA-256 of `QQQ_EMAIL_BODY_KEY`.
+Missing keys refuse the send before an outbox insert. Only dispatch decrypts; query,
+record and API displays show `[encrypted]`, while home shows `Secure message`.
+Resend preserves ciphertext and policy; its token snapshot stays bound to the original
+message, which the new message links to. Errors and logs omit provider diagnostics
+and content. Keys resolve through `secretResolver`; no secret values are stored.
+
+NOTIFICATION/MARKETING templates prepare footer links and headers using
+`QQQ_EMAIL_UNSUBSCRIBE_KEY` and `publicBaseUrl`; marketing refuses without them.
+Tokens bind the message, recipient-envelope hash and category. The receiving route
+is implemented: GET only shows a light/dark confirmation page; explicit POST upserts
+category suppression and records UNSUBSCRIBED. Invalid or account/security tokens
+return 404. The legacy token covers every To/Cc/Bcc recipient, so use one mailbox
+per opt-out message for individual preferences. Preferences UI remains deferred
+until core #1162 ships in an RC.
+
+The home uses viewer-scoped counts and queries, UTC hour/day charts, a central
+health status line, and 20 recent messages with masked recipients. No sample data or sampled
+counts are used. Delivered/bounced/complained totals count recipient events and
+use their occurred dates; sent/dead-letter totals count messages.
+
 ## Delivery and actions
 
 Each claim inserts a unique `(message_id, attempt_number)` row and commits SENDING
@@ -191,16 +525,54 @@ Providers offer Send Test Email with a recipient input and a reported outcome.
 
 `email_send_templated` is a hidden backend API process. Inputs include `templateName`,
 `to`, `cc`, `bcc`, `replyTo`, `subject`, `markdownBody`, `htmlBody`, `textBody`,
-`providerName`, `brandName`, `category`, `variablesJson`, `linkedTableName`,
-`linkedRecordId`, and `idempotencyKey`. Ad-hoc content works now; template/brand/variable
-inputs return REFUSED until part 2. Output includes `messageId`, `status`, and `reasons`.
+`providerName`, `brandName`, `category`, `locale`, `variablesJson`, `recordVariablesJson`,
+`linkedTableName`, `linkedRecordId`, and `idempotencyKey`. `variablesJson` is an object;
+record bindings use `{"patient":{"table":"patient","id":123}}` in
+`recordVariablesJson`. Output includes `messageId`, `status`, and `reasons`.
 
-Hidden schedules are `email_dispatch` (15 s by default), `email_maintain` (300 s, lease
+Hidden schedules include `email_process_webhooks` (30 s), `email_dispatch` (15 s by default), `email_maintain` (300 s, lease
 recovery including disabled providers, and health probes), and `email_retention`
 (daily). Retention clears final-message bodies after 30 days, preserving `bodySha256`;
 message deletion is disabled by default. `finishedDate` records finalization independently
 of enqueue and later retention updates.
 
+## Delivery tracking
+
+Apply the new `email_webhook_inbox` and `email_event` DDL plus indexes for an existing
+phase-(a)/(b) database. Configure the authenticated HTTPS endpoints using
+[the provider guide](docs/PROVIDERS.md#event-webhooks). Verification supports SNS
+RSA v1/v2 with pinned topic and AWS certificate hosts, Postmark Basic auth,
+SendGrid ECDSA and Mailgun HMAC with durable nonce replay protection.
+
+The 1 MiB receiver persists before acknowledging. DB transactions serialize
+processing across replicas and commit event rows, message state and suppression
+atomically. Events in a payload are applied independently: matched events commit at
+once, and only unmatched events (or events whose message is still SENDING) retry the
+row with configured backoff. After six attempts they are skipped and the row finishes
+PROCESSED with a note ("N events did not match a message"). Rows that cannot be parsed
+or written fail after six attempts; **Reprocess** on FAILED inbox rows uses the
+standard Review/Result flow. An event whose recipient is not on the matched message
+is ignored, and an SES bounce or complaint without its recipient list is skipped.
+SNS notifications older than an hour or more than five minutes ahead are refused, and
+certificate fetch failures are cached for five minutes per URL. Disabled tracking is
+ignored. Per-event recipient keys deduplicate
+overlapping batches. All new service state is in the DB; certificate caches are in
+memory. No runtime filesystem or new dependencies are used.
+
+Hard bounce/complaint suppress ALL; provider unsubscribe suppresses the message's
+opt-out category. Message status never regresses from COMPLAINED to BOUNCED or
+DELIVERED. Optional `email.complaint` alerts warn after more than three complaints
+in 24 hours, with daily deduplication. Provider details mask addresses and are capped
+at 500 characters; raw authenticated inbox payloads are sensitive DB data.
+
+NOTIFICATION and MARKETING messages with unsubscribe configured require exactly one
+To recipient and no Cc/Bcc; send one message per recipient. The token binds that
+mailbox, and an unsubscribe POST suppresses only that address for the message's
+category. Multi-recipient requests are refused before suppression filtering.
+TRANSACTIONAL and SECURITY messages, and NOTIFICATION messages without unsubscribe
+configured, may still have multiple recipients. Existing single-recipient links
+remain valid; old multi-recipient links are rejected.
+
 ## Core messaging bridge
 
 The producer adds messaging provider `qbitEmail` (configurable), type `QBIT_EMAIL`.
@@ -218,6 +590,11 @@ The bridge recursively maps Party/MultiParty TO, CC, BCC, FROM and REPLY_TO role
 TEXT/HTML alternatives. REFUSED throws `QException`; successful calls acknowledge
 queueing, not delivery. The built-in EMAIL and SES types are unchanged.
 
+For schema-aware calls from another qbit, use `EmailApi.send` with an
+`EmailApiRequest` and declared template variables as described above. Ordinary
+core `SendMessageInput` is ad-hoc and cannot infer classifications from arbitrary
+pre-rendered text. The existing typed bridge extension is an internal interface.
+
 ## Configuration
 
 All settings have fluent `withX` setters and getters.
@@ -226,7 +603,10 @@ All settings have fluent `withX` setters and getters.
 |---|---|
 | `backendName` | Required existing backend |
 | `schedulerName` | Optional existing scheduler; required for automatic dispatch |
-| `publicBaseUrl` | Reserved for later unsubscribe links |
+| `publicBaseUrl` | Public app URL for signed unsubscribe links |
+| `webhookBasePath` | `/qqq/hooks/email`; absolute path outside `/qqq/v1` |
+| `mjmlCompiler` | Optional `MjmlCompilerInterface`; required for MJML activation |
+| `classificationOverrides` | Map of `table.field` to `EmailClassifications.Level` for RC.5 |
 | `defaultProviderName` | Optional named provider override; otherwise enabled default row |
 | `bridgeProviderName` | `qbitEmail` |
 | `secretResolver`, `allowedEnvNames` | `System::getenv`, empty additional allowlist |
@@ -250,9 +630,36 @@ modules to these declarations.
 ```
 
 Windows can use `./mvnw.cmd -o -q verify`. No new dependencies are required. Tests use
-H2, GreenMail and a fake SES client, including transaction rollback, concurrent claims,
+H2, GreenMail, a fake SES client and local HTTP servers, including transaction rollback, concurrent claims,
 concurrent idempotency, shared rate budgets, health recovery and process screens.
-See [implementation notes](docs/PART1-NOTES.md) for design/API accommodations.
+The tests also exercise template lifecycle, parent-scoped possible values, rendering,
+PHI canary egress, encryption, preview widgets and home data.
+
+## Durable jobs
+
+Built on QQQ **4.1.0-RC.8**. Enable `DurableJobsMetaData` and define the jobs tables
+**before** producing the email qbit: `EmailQBitProducer` automatically registers
+`EmailJobEffectTarget` under target name `email`. If jobs are enabled later, call
+`EmailJobEffectTarget.register(instance)` afterward. Registration is a no-op when
+jobs are disabled.
+
+Declare `new JobEffectDeclaration("welcomeEmail", "<step>", "email",
+JobEffectType.IDEMPOTENT_EXTERNAL)` in the process's `DurableProcessMetaData`, then
+call `JobEffects.emit(input, "welcomeEmail", rowKey, payload)` in the backend step.
+The payload accepts recipients, template or ad-hoc bodies, variables, routing and
+record linkage; see the [complete payload contract and examples](docs/DURABLE-JOBS.md).
+
+The target deduplicates handoffs by the effect key. SENT means the email outbox has
+committed, while its dispatcher owns provider delivery and retries. Job effects
+send under the job owner's current session and captured security scope; an owner
+whose session cannot be established produces FAILED. Other exceptions produce
+UNKNOWN and can safely be retried using the same key. Reconcile finds the existing
+outbox row, including terminal audit rows.
+
+Each message retains its stored RFC Message-ID across provider attempts. SMTP,
+Postmark, SendGrid and Mailgun carry it; SES replaces it downstream. This supports
+correlation and receiver deduplication where available, without guaranteeing
+exactly-once inbox delivery. See the [schema upgrade and provider notes](docs/DURABLE-JOBS.md).
 
 ## License
 

UPGRADE.md

@@ -0,0 +1,23 @@
+# Upgrading
+
+## Unreleased: shared CRM templates
+
+Existing hosts and callers need no configuration change. This release adds APIs and a template kind; it does not migrate CRM rows or enable shared CRM templates automatically. The existing VARCHAR kind column needs no email schema change. Hosts with additional kind constraints must allow `CRM_LEGACY` before importing migrated rows.
+
+- To grant CRM users template access, configure `EmailQBitConfig.withTemplatePermissionBaseName("crm.manage")`. The resulting `.read` and `.write` permissions apply to template/version data and the New Version/Activate Version actions, plus app navigation. They do not grant provider, brand, delivery, message or PHI approval access. A template's `editPermissionName` is still an additional write requirement, and record security locks still apply.
+- `EmailApi.templateVariableNames` and `renderTemplate` read templates and active versions in the caller's session. Rendering requires an expected delivery category and returns typed content and provenance. Native HTML must not be interpreted as Markdown. Native templates reject category/content overrides, and PHI-approved templates require the existing protected send path. Preview content is not a substitute for the actual queued message subject or delivery envelope.
+- `EmailApi.sendTemplateOnce` uses the existing outbox and suppression rules, returning the exact stored subject only for a checked template/version and matching sender, linked record, category and single-recipient envelope. Supply sender qbit/process and linked table/id; CC/BCC and multiple parsed mailboxes are unsupported. Existing metadata-only lookup APIs remain unchanged. A replay after active-version or envelope changes can be rejected: reconcile the existing effect rather than automatically retrying with a new key.
+- `CRM_LEGACY` is for migrated templates owned by `crm`, without PHI approval or record bindings. It preserves the five historical CRM substitutions in a single pass, leaves unknown syntax literal, prefers text source over HTML fallback, and supports historical subject/body overrides. It permits the caller's transactional or marketing category while retaining delivery suppression and readiness checks. Native kinds keep their existing policies.
+- Release the public email artifact before pinning the adopting CRM release. CRM/host adoption must explicitly opt in, migrate populated rows and references, and preserve provenance and rollback data during a documented maintenance window. Optional tenant CRM hosts must retain their legacy path until a supported tenant migration exists. Local verification artifacts such as `0.1.0-LOCAL-270` must never become public dependency pins.
+
+## Unreleased: starter defaults, setup card, table help
+
+1. **Add the defaults changelog** after the changesets that create the `email_*` tables (`docs/ddl/email-postgres.sql`) in the host's master changelog:
+
+   ```yaml
+   - include: { file: db/liquibase/qbit-email/email-defaults.changelog.sql }
+   ```
+
+   It is insert-only and guarded: a host that already has any brand gets nothing, a host without the table skips it. The `neutral` brand it adds is not the default brand, so existing mail renders exactly as before.
+2. **Behavior change.** Messages sent from a template whose Owner Qbit is set, with no sender named in the request, now record that qbit as `senderQbit` (it was empty). Nothing else about sending changes.
+3. The help bundle and the Setup card need no configuration. Existing built-in templates created before this release keep an empty Owner Qbit.

docs/DESIGN.md

@@ -1,6 +1,6 @@
 # qbit-email design
 
-**Status:** spec. Phases (a) to (d) build outbound; phase (e) is inbound (section 12, design only).
+**Status:** phases (a), (b) and (c) implemented, except Preferences (8.3), deferred until core #1162 ships in an RC. Phase (d) consumer migrations and phase (e) inbound remain specification.
 **Brief:** owner decisions of 2026-10-13 (providers, outbound first, both template kinds).
 **Owner decisions (2026-10-12): all recommendations accepted.** Every "Recommended" choice and
 every decision below stands; it is adjusted once it can be seen working.
@@ -20,7 +20,8 @@ unsubscribe and PHI rules.
 | D7 | Hard bounces and complaints suppress the address. One-click unsubscribe (RFC 8058) records a suppression for the message's category, and users see it as a Preferences section (core #1162). |
 | D8 | PHI-safe by default: PII/PHI-classified variables are refused unless the template is `phi_approved`. The recommended PHI pattern is a "secure message" (a sign-in link, no PHI in the body). |
 | D9 | Gmail: SMTP with an app password in phase (b), as a preset of the SMTP transport. The Gmail API with OAuth is specified (section 3.6) and built only on request. |
-| D10 | MJML is compiled when a version is activated, by a pluggable compiler (default: the `mjml` CLI when configured). Sends never need the compiler; HTML templates need nothing. |
+| D10 | MJML is compiled when a version is activated, by a pluggable compiler (default: the `mjml` CLI when configured, through stdin and stdout). Sends never need the compiler; HTML templates need nothing. |
+| D11 | Owner rule (2026-10-13): no files or filesystem, only the database and S3. Attachments, rendered bodies and (phase e) inbound mail live in the database or in object storage (qbit-object-storage), never on local disk; the services are stateless, so any replica can send, receive a webhook or render a preview. |
 
 ## 1. Flow
 
@@ -43,7 +44,7 @@ unsubscribe and PHI rules.
 
 ## 2. Sending API
 
-### 2.1 `EmailService` (Java, for every consumer)
+### 2.1 `EmailService` (internal Java enqueue service)
 
 ```java
 EmailSendResult result = EmailService.send(new EmailRequest()
@@ -53,6 +54,7 @@ EmailSendResult result = EmailService.send(new EmailRequest()
    .withRecordVariable("order", "order", 1234)     // a record, read as the sender; classification known
    .withCategory(EmailCategory.NOTIFICATION)       // default: the template's
    .withProviderName("pmg")                        // optional; else the default provider
+   .withFromAddressId(4)                           // optional enabled email_provider_sender_address row of that provider
    .withBrandName("kof22")                         // optional; else the template's, else the default brand
    .withIdempotencyKey("alerts:notif:991")         // optional; a repeat returns the existing message
    .withLinkedRecord("alerts_alert", 991)          // shown as a link on the message record
@@ -72,7 +74,8 @@ EmailSendResult result = EmailService.send(new EmailRequest()
 
 ### 2.2 Process `email_send_templated`
 The same request as a backend process (template, to, cc, bcc, variables JSON, linked table and
-id, idempotency key, provider, brand) for scripts, the API and other qbits. Not in the nav;
+id, idempotency key, provider by `providerId` or `providerName`, `fromAddressId` filtered by the
+chosen `providerId`, brand) for scripts, the API and other qbits. Not in the nav;
 callable through the API and `/qqq/v1/processes`.
 
 ### 2.3 Permissions
@@ -91,11 +94,60 @@ template may set `edit_permission_name` to restrict who edits it (e.g. marketing
   TRANSACTIONAL unless configured) and enqueues it. It throws on `REFUSED`, so callers still see
   failures; delivery is then asynchronous.
 - Attachments are stored through qbit-object-storage when it is installed, else refused with a
-  plain message (no blobs in the outbox).
+  plain message (no blobs in the outbox, nothing on local disk: D11).
 - Callers (qbit-alerts `EmailChannel` and `NotificationEmailer`, qbit-marketing
-  `QqqMessagingEmailTransport`) can switch by configuration at once, then move to `EmailService`
+  `QqqMessagingEmailTransport`) can switch by configuration at once, then move to `EmailApi`
   in phase (d) for templates, categories, idempotency and linked records.
 
+### 2.5 Public API
+
+`com.kingsrook.qbits.email.api.EmailApi` is the sole public qbit-email surface for consuming qbits.
+Changes within a `0.x` minor release line are additive only. Public/protected
+signatures contain only JDK, QQQ core or API-package types; internal packages are
+not API and may change. A reflection test discovers every compiled API class and
+checks signatures, including generic arguments, bounds and nested types.
+
+- `EmailApi.send(EmailApiRequest)` maps to the existing outbox service, preserving
+  permissions, schema/PHI validation, suppression and one-recipient rules. Requests
+  cover recipients/sender selection, body alternatives, template variables and record
+  provenance, category/provider/brand/locale, idempotency, linked records, producer
+  identity, scheduling and caller transactions (`withTransaction(transaction, backendName)`).
+  Results expose message id, enqueue status and reasons.
+- `sendOnce(EmailApiRequest, effectKey)` provides durable handoff through the existing
+  internal effects implementation. The key becomes the request's idempotency key;
+  null requests, missing/blank/over-500-character keys, mismatches and caller transactions
+  are refused. `EmailApiEffectResult` carries `EmailApiEffectOutcome.QUEUED_OR_DUPLICATE`
+  or `REFUSED` and nullable `EmailApiMessage`. Success means committed outbox storage,
+  and replays retain the row and RFC Message-ID. Suppressed audit rows remain refused
+  on replay and return metadata; refusals without a row return null. Operational
+  failures throw `QException`. The deprecated `EmailEffects`, `EmailEffectOutcome` and
+  `EmailMessageRef` remain internal; consumers use this API. See [durable jobs](DURABLE-JOBS.md).
+- `ensureTemplate(EmailApiTemplate)` delegates create-once template registration;
+  `EmailApiVariable` carries the variable contract. Existing content is never
+  overwritten, and the API does not confer PHI approval.
+- `getMessage`, exact `getMessageByIdempotencyKey`/`getMessageByRfcMessageId` and
+  bounded, literal `findMessagesByIdempotencyKeyPrefix` perform
+  system reads of an explicit metadata projection: id/status/category, idempotency
+  key, RFC Message-ID and provider id, template name, linked record and create/sent/delivered dates.
+  Exact-key lookups return empty for null/blank/missing values. RFC lookup requires
+  the exact bracketed header stored at enqueue time, distinct from provider response ids.
+  No recipients, subjects, bodies or snapshots are fetched or returned by lookups.
+  Callers own authorization before presenting metadata to users.
+- `isInstalled`, `defaultProviderName`, `listSenderAddresses` and `readiness` replace
+  consumer access to runtime/configuration/tables. Readiness checks an enabled
+  default provider; MARKETING also needs a valid publicBaseUrl, available unsubscribe
+  key and default brand postal address. The PHI overload checks body key availability
+  and provider PHI/tracking policy. Reasons never contain resolved secret values.
+  PHI is a template state, so it is an explicit option rather than a fifth category.
+- Database operations use the current `QContext`; an installed instance argument
+  must match that context. Database errors remain core `QException`. Readiness does
+  not validate an individual request or guarantee delivery.
+
+For simple subject/body sends, consumers need no qbit-email dependency: use core
+`SendMessageAction` with `messagingProviderName = "qbitEmail"` (or the host's
+configured bridge name). Use the API package for templates, idempotency, links and
+lookups. Both routes enqueue; neither sends inline.
+
 ## 3. Providers and transports
 
 ### 3.1 `email_provider`
@@ -121,7 +173,16 @@ They are never stored, logged, audited, put in process output or returned. The r
 whether each named variable is set (yes or no), never the value.
 
 **Record action "Send Test Email"** (`email.admin`): queues a fixed test message to a given
-address through that provider and reports the outcome on the standard result screen.
+address through that provider and reports the outcome on the standard result screen. An optional
+`fromAddressId` picker lists only that provider's sender addresses.
+
+**Sender addresses** (`email_provider_sender_address`, a child list on the provider, `email.admin`):
+provider_id, address (validated, lowercase), display_name, is_default (at most one enabled default
+per provider), enabled, note; unique (provider_id, address); the domain must equal `sending_domain`
+when that is set. The provider's `from_address` / `from_name` remain the fallback; an enabled default
+row wins when present. A chosen id, or an explicit from text once the provider has rows, must match an
+enabled row of the resolved provider or the send is `REFUSED` ("That from address is not set up for
+provider <name>"). The row used is kept as `email_message.from_address_id`.
 
 ### 3.2 `EmailTransport` SPI (in the qbit)
 ```java
@@ -173,6 +234,7 @@ transient; other 4xx are permanent.
 | variables_snapshot | JSON, redacted per section 7.3 |
 | html_body, text_body | rendered at queue time so retries send the same bytes; encrypted for `phi_approved`; cleared after `bodyRetentionDays` (default 30) once final, keeping `body_sha256` |
 | idempotency_key | unique when present |
+| rfc_message_id | STRING(500), unique; stored once at enqueue and reused on every attempt; see [durable job effects](DURABLE-JOBS.md) |
 | provider_id, provider_message_id | |
 | attempt_count, next_attempt_date, lease_expires_date, last_error, sent_date, delivered_date, dead_letter_date | |
 | linked_table_name, linked_record_id | rendered as a link on the record screen |
@@ -204,7 +266,9 @@ error) and `email_event` (section 6).
   content), Cancel (queued or waiting), Send Now (waiting). Standard streamed-ETL Review and Result
   screens.
 - **Retention:** a daily job clears bodies after `bodyRetentionDays` and deletes final messages
-  older than `messageRetentionDays` (0 = keep forever; kof22 keeps).
+  older than `messageRetentionDays` (0 = keep forever; kof22 keeps). NOTIFICATION and MARKETING
+  messages are never deleted, because their unsubscribe links resolve through the message row
+  (8.2); at `messageRetentionDays` retention only clears their bodies and variable snapshot.
 
 ## 5. Templates and branding
 
@@ -254,11 +318,39 @@ the exact version it used.
   version, else the default locale's. One locale (`en`) ships.
 
 ### 5.3 Preview
+
+**Part 2 status:** standard record widget implemented. Next's sanitizer removes
+iframes and style blocks, so it uses sanitized inline light (390px maximum) and dark
+(600px maximum) samples, with wrapping plain text. Draft MJML previews compile in memory
+with the configured compiler; stored versions are unchanged. TODO: endpoint arrives with RC.6.
+
 Each version record shows a **Preview** widget: the rendered email with the sample variables in a
 sandboxed iframe (`srcdoc`, scripts disabled), Light/Dark and 390/600 px toggles, and the plain
 text. It is served through the UI API (section 10): `POST /qqq/v1/qbit/email/preview` (a version
 id, or unsaved source, plus variables) returns subject, html, text and warnings.
 
+### 5.4 Part 2 implementation choices
+- Approval records `approved_version_id` on the template. An approved DRAFT freezes;
+  approve a new sensitive version before activation. Activating a different,
+  unapproved version clears approval. Approval is specific to one locale version.
+- `EmailBuiltIns.ensure()` seeds `email_secure_message` on its first send, using the
+  database unique name and a transaction, with no static bootstrap cache.
+- `dark_primary_color` and `dark_button_text_color` optionally override their light
+  counterparts; both button pairs are contrast-checked. Brand colors use #RRGGBB.
+- `EmailTemplatedMessageInput` extends core SendMessageInput for schema variables and
+  record references. Ordinary core input remains compatible ad-hoc content.
+- RC.5 QueryAction masks passwords but does not apply ordinary FieldSecurityLock;
+  record-variable loading additionally applies that lock to sender session keys.
+- The real outbox id is bound during the enqueue transaction, before commit. Failed
+  validation persists no message. Resends preserve encrypted content and its original
+  token snapshot, linking to the original message for the token binding.
+- The home follows the newer Alerts pattern: standard QQQ chart widgets plus inline,
+  theme-neutral cards. All queries/counts use the viewer's session. Bounce/complaint
+  dates are populated by phase-(c) events; home totals count those recipient events.
+- Part 2 signs opt-out links and prepares headers; phase (c) now serves the receiver. Without its key/base URL, notification omits opt-out links and
+  headers, while marketing refuses as specified in 8.2. Do not use opt-out delivery
+  without a receiving handler. The token's address hash binds the single recipient mailbox.
+
 ## 6. Delivery tracking
 
 ### 6.1 Inbound route
@@ -282,6 +374,32 @@ DEFERRED, BOUNCED, COMPLAINED, OPENED, CLICKED, UNSUBSCRIBED, REJECTED), bounce_
 UNDETERMINED), recipient, occurred_date, detail (the provider's reason, truncated; never body
 content), url (clicks only). Opens and clicks are stored only when the provider row enables them.
 
+### 6.3 Phase (c) implementation
+- Inbox states: PENDING, PROCESSED, FAILED, IGNORED. Retry after configured backoff,
+  FAILED after six attempts, and a standard Reprocess action resets FAILED to PENDING.
+- Events in one payload are applied independently. Only unmatched events (or events whose
+  message is still SENDING) defer the row; on the sixth attempt they are skipped and the row is
+  PROCESSED with the note "N events did not match a message". Suppression applies only to a
+  recipient in the matched message's to, cc or bcc; an SES bounce or complaint without its
+  recipient list is skipped, never widened to all destinations. SNS notifications must carry a
+  Timestamp no older than 1 hour and no more than 5 minutes ahead, and certificate fetch
+  failures are cached for 5 minutes per URL.
+- A short DB transaction locks the common provider gate then the actual provider;
+  it rechecks the observed inbox attempt and commits all changes together. No worker
+  filesystem, extra claim table, in-process scheduler or network operation is needed
+  during processing. A crash rolls back the transaction and releases the claim.
+- `email_event.event_key` provides unique recipient/event deduplication across
+  overlapping batches, alongside inbox uniqueness on provider/event and provider/nonce.
+- Message correlation always stays within the authenticated provider. Unknown message
+  ids retry (including callbacks before SENT); unsupported event kinds are ignored.
+- Opens/clicks require current provider flags and are also dropped for PHI-approved
+  messages. Event details mask addresses before truncation to 500 characters.
+- The unsubscribe signer binds one mailbox. A valid POST suppresses only that address
+  for MARKETING/NOTIFICATION; the page never displays addresses. Legacy links remain
+  valid only for messages with one To recipient and no Cc/Bcc.
+- PostgreSQL and H2 definitions, crypto fixtures and real random-port Javalin tests
+  are included. Certificate caching is memory-only. Setup is in `PROVIDERS.md`.
+
 ## 7. PHI and PII
 
 ### 7.1 Classification
@@ -304,9 +422,20 @@ schema.
 
 ### 7.3 Redaction and storage
 Following core `docs/SECURED-DATA.md` (section 15, QRun-IO/qqq#1161):
-- `variables_snapshot`: PII/PHI values become `hmac:v1:<keyId>:<b64url>` (HMAC-SHA256 with the
-  instance audit key `QQQ_AUDIT_HMAC_KEY`, over template␟variable␟message␟canonical value), or
-  `changed:v1` with no key; low-entropy values (booleans, small enums) are shredded (`shred:v1`).
+- `variables_snapshot`: PII/PHI values become tokens in the format of core
+  `ClassifiedValueTokens` (package `...core.actions.permissions.fieldaccess`, SECURED-DATA §14.5):
+  `hmac:v1:<keyId>:<b64url(HMAC-SHA256(key, m))>`, with `m` joined by `` and the canonical
+  value last, and the instance key from `QQQ_AUDIT_HMAC_KEY` (base64).
+  - **Record-bound variables** use the record binding, `m = table␟field␟pk␟canonical(value)`
+    (`forRecordField`), so the token matches the audit's and a field under a wipe rule gets
+    `shred:v1` with the same per-record-field key: a wipe also shreds the outbox snapshot.
+  - **Other values** use a domain-prefixed binding,
+    `m = "email"␟template␟variable␟messageId␟canonical(value)` (`forContext`), so they never
+    collide with a record binding. They get `hmac:v1` only; a low-entropy value (booleans, values
+    with under 4 distinct characters) gets `changed:v1`, because there is no record key to shred.
+  - No key configured: `changed:v1`.
+  - Until core ships the helper, the qbit carries `EmailValueTokens`, marked
+    `STAND-IN(core=#1161-impl, removeBy=RC.7)`, with the same names and output.
 - The subject and bodies of `phi_approved` messages are stored AES-256-GCM encrypted with a key
   from `QQQ_EMAIL_BODY_KEY` (no key: `phi_approved` sends are refused) and cleared after
   `bodyRetentionDays` once final.
@@ -330,6 +459,7 @@ MANUAL), source_message_id, source_event_id, note, created_date, expires_date (o
   respects HARD_BOUNCE and COMPLAINT.
 
 ### 8.2 One-click unsubscribe (RFC 8058, RFC 2369)
+- NOTIFICATION or MARKETING messages carrying an unsubscribe link/header must have exactly one To recipient and no Cc/Bcc; send one message per recipient.
 - MARKETING and NOTIFICATION messages carry
   `List-Unsubscribe: <https://{publicBaseUrl}/qqq/hooks/email/unsubscribe/{token}>` and
   `List-Unsubscribe-Post: List-Unsubscribe=One-Click`, and the footer links to the same URL.
@@ -338,17 +468,20 @@ MANUAL), source_message_id, source_event_id, note, created_date, expires_date (o
   MARKETING sends are refused. Tokens do not expire (RFC 8058 expects the link to keep working).
 - `POST` with `List-Unsubscribe=One-Click` records the suppression and returns 200. `GET` returns a
   minimal page with one "Unsubscribe" button that POSTs, because mail scanners prefetch GETs; then
-  "You are unsubscribed from {category}", with a link to Preferences.
+  "You are unsubscribed from {category}". A Preferences link awaits core #1162.
 - An `UNSUBSCRIBED` event is recorded on the message.
 
 ### 8.3 Preferences (core #1162)
-The qbit registers a Preferences section `email` ("Email") whose provider
+**Deferred: core #1162 is not in an RC.** The planned qbit registers a Preferences section `email` ("Email") whose provider
 (`EmailPreferenceProvider implements UserPreferenceProviderInterface`) maps the signed-in user's
-address to `email_suppression` rows: one toggle per opt-out-able category (NOTIFICATION,
+address (`UserPreferenceRequestContext.getUserEmailAddress()`, never an address from the request)
+to `email_suppression` rows: one toggle per opt-out-able category (NOTIFICATION,
 MARKETING) and read-only rows saying that account and security mail is always sent. Qbits with
 finer settings keep their own sections: qbit-alerts' "Notifications" decides which alerts are
 emailed; this section decides whether NOTIFICATION mail reaches the address at all. It is built
-once #1162 is in an RC; one-click unsubscribe does not depend on it.
+once #1162 is in an RC; one-click unsubscribe does not depend on it. With no address on the
+account, the rows are read-only ("No email address on your account") and writes are refused. The
+section's description explains the split with qbit-alerts' Notifications section.
 
 ## 9. Integrations
 - **Alerts (core `QAlerts`, #1108):** called reflectively when present (section 4.2).
@@ -408,13 +541,15 @@ once #1162 is in an RC; one-click unsubscribe does not depend on it.
 | `email_brand` | yes | people |
 | `email_suppression` | yes | people and the qbit |
 | `email_provider` | yes | admins |
+| `email_provider_sender_address` | relation (on the provider) | admins |
 | `email_webhook_inbox` | relation (on the provider) | the qbit |
 | `email_inbound`, `email_inbound_attachment` | phase (e) | the qbit |
 
-Postgres DDL in `docs/ddl/email-postgres.sql` (phase a).
+Postgres DDL in `docs/ddl/email-postgres.sql` (phases a-c).
 
 ## 14. Configuration (`EmailQBitConfig`)
-backendName (required), schedulerName (required to send), publicBaseUrl (unsubscribe links),
+backendName (required), schedulerName (required for automatic processing), publicBaseUrl (unsubscribe links),
+webhookBasePath (`/qqq/hooks/email`, shared by tracking and unsubscribe),
 defaultProviderName, bridgeProviderName (`qbitEmail`), secretResolver, allowedEnvNames,
 dispatchIntervalSeconds (15), batchSize (100), maxAttempts (6), retryMinutes, leaseSeconds (120),
 bodyRetentionDays (30), messageRetentionDays (0), mjmlCompiler, classificationOverrides, appName
@@ -423,14 +558,14 @@ and appLabel, securityFields and recordSecurityLocks (multi-tenant hosts).
 ## 15. Phases and acceptance
 | Phase | Scope | Acceptance (tests) |
 |---|---|---|
-| (a) | tables, outbox and dispatcher, SMTP and SES, Markdown templates and versions, brands and the layout, preview, EmailService, the process, the core bridge, PHI refusal and redaction, the app home | GreenMail SMTP sink end to end; SES through a mocked `SesV2Client`; the claim race (two runners, each message sent once); retry, dead letter, idempotency; rendering (variables, escaping, `#if`/`#each`, plain text, dark-mode contrast); PHI refusal; snapshot redaction; the canary test; producer standards (names, nav, permissions) |
-| (b) | Postmark, SendGrid, Mailgun, Gmail SMTP; MJML and HTML templates | HTTP mocks per provider (success, 4xx permanent, 429/5xx transient); MJML through a fake compiler; the Gmail preset |
-| (c) | webhook route and inbox, events, suppression, unsubscribe, Preferences section | signature verification per provider (valid, tampered, stale, missing secret); the SNS certificate host rule; suppression on hard bounce and complaint; one-click POST and the GET page; category rules |
+| (a) | tables, outbox and dispatcher, SMTP and SES, Markdown/HTML/MJML templates and versions, brands and the layout, preview, EmailService, the process, the core bridge, PHI refusal and redaction, the app home | GreenMail SMTP sink end to end; SES through a mocked `SesV2Client`; the claim race (two runners, each message sent once); retry, dead letter, idempotency; rendering (variables, escaping, `#if`/`#each`, plain text, dark-mode contrast); PHI refusal; snapshot redaction; the canary test; producer standards (names, nav, permissions) |
+| (b) | Postmark, SendGrid, Mailgun, Gmail SMTP | HTTP mocks per provider (success, 4xx permanent, 429/5xx transient); the Gmail preset. HTML/MJML moved into part (a), part 2 at owner request. |
+| (c) | webhook route and inbox, events, suppression, unsubscribe (Preferences deferred) | signature verification per provider (valid, tampered, stale, missing secret); the SNS certificate host rule; suppression on hard bounce and complaint; one-click POST and the GET page; category rules |
 | (d) | consumer migrations | each consumer's own tests; a contract test of `EmailService` |
 | (e) | inbound | design only for now |
 
 Dependencies: phase (a) builds on QQQ 4.1.0-RC.5 with the classification stand-in, and moves to
-RC.6 for `DataClassification` and Preferences.
+later RCs for `DataClassification` and Preferences when their APIs are released.
 
 ## 16. Owner steps (outside code)
 - **PMG (kof22):** none; the relay already accepts the cluster.

docs/DURABLE-JOBS.md

@@ -0,0 +1,186 @@
+# Durable job email effects
+
+QQQ 4.1.0-RC.7 supplies the durable jobs side-effects outbox. QBit Email registers
+`com.kingsrook.qbits.email.outbox.EmailJobEffectTarget` as target `email` to hand
+those effects to its own committed outbox. All provider sending remains asynchronous.
+
+## Stored identity and schema upgrade
+
+`email_message.rfc_message_id` (`rfcMessageId` in metadata) is a unique STRING(500)
+shown in the message T2 details. Before insertion, the service stores
+`<token@domain>`, where `token` is the first 32 lowercase hex characters of SHA-256
+of the UTF-8 idempotency key. Without a key, the seed is `qbit-email:` plus a fresh
+UUID, since the row id is not yet allocated. The domain is the normalized From
+mailbox domain, excluding display names; unavailable or unsuitable domains use
+`qbit-email.local`. The key itself is never included in the header.
+
+The dispatcher reads this stored value on every attempt. JavaMail's
+`updateMessageID()` is overridden so repeated `saveChanges()` calls cannot replace
+it. A manual **Resend** creates a new outbox row and a new identity; a delivery retry
+keeps its identity. `providerMessageId` remains the provider's response identifier,
+distinct from `rfcMessageId` and the numeric outbox `id`.
+
+New installations use [email-postgres.sql](ddl/email-postgres.sql). Existing
+PostgreSQL installations must pause enqueue and dispatch, then apply
+[email-message-id-upgrade.sql](ddl/email-message-id-upgrade.sql) before starting
+this version. The migration backfills old rows using the existing key, or
+`qbit-email:` plus the already allocated row id, and the stored From domain.
+It cannot recover previously generated random transport Message-IDs. Review host
+schema adaptations first; host security columns are unaffected.
+
+## Provider behavior
+
+| Transport | Request mechanism | Identity preservation |
+|---|---|---|
+| SMTP / Gmail SMTP preset | MIME `Message-ID` | Sent unchanged by this transport; downstream relay policy still applies |
+| SES v2 | Raw MIME `Message-ID` | **SES replaces Message-ID downstream** |
+| Postmark | `Headers: [{Name: "Message-ID", Value: "<...>"}]` | Custom Message-ID supported |
+| SendGrid | `headers: {"Message-ID": "<...>"}` | Sent as a custom header |
+| Mailgun | MIME Message-ID plus multipart `h:Message-Id` | Sent in the `/messages.mime` request |
+
+All transports retain `X-QQQ-Email-Id` with the numeric outbox id. Postmark's
+`MessageID`, SendGrid's response `X-Message-Id`, and SES's returned id are provider
+references, not our RFC header. A fixed header enables recognition and receiver
+deduplication where supported, but is not an exactly-once inbox guarantee.
+
+Provider references: [Postmark custom Message-ID](https://postmarkapp.com/developer/user-guide/send-email-with-api/send-a-single-email),
+[SendGrid custom headers](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send),
+[Mailgun sending parameters](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/messages/post-v3--domain-name--messages),
+and [SES header replacement](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendRawEmail.html).
+
+## Handoff and reconcile
+
+`EmailApi.sendOnce(EmailApiRequest request, String effectKey)` sets the request's key, refusing
+a different pre-existing key, a missing/blank/over-500-character effect key, a null request
+or a caller transaction. The service performs its usual validation and send
+permission checks. Success is returned only after the outbox transaction commits;
+there is no transport call here. Use ordinary `EmailApi.send` with
+`request.withTransaction(transaction, backendName)` for caller-owned or cross-backend
+deferred transactions. `sendOnce` refuses either kind of caller transaction.
+
+`EmailApiEffectResult(outcome, message)` contains an `EmailApiEffectOutcome` and a
+nullable `EmailApiMessage` with the outbox id, current delivery status, RFC Message-ID,
+provider reference and other metadata. All these types are in
+`com.kingsrook.qbits.email.api`, the sole public qbit-email surface:
+
+- `QUEUED_OR_DUPLICATE`: one committed row accepted the handoff, including replays.
+- `REFUSED`: invalid or suppressed request. A suppressed audit row has a reference;
+  refusals without a stored row have a null reference. Replaying a suppressed row
+  stays refused even though `EmailService` returns `DUPLICATE`.
+- Database/query failures throw `QException`; callers must retry or reconcile,
+  never turn an uncertain outcome into a permanent refusal.
+
+`EmailApi.getMessageByIdempotencyKey(key)` and `EmailApi.getMessageByRfcMessageId(messageId)`
+return `Optional<EmailApiMessage>` from system reads of an explicit metadata projection.
+They return empty for null/blank/missing values. These are trusted backend APIs,
+not viewer-scoped public endpoints. Lookups reflect current status and provider
+reference and do not expose bodies, recipients or variables. `EmailApi.getMessage(id)`
+and `EmailApi.findMessagesByIdempotencyKeyPrefix(prefix, limit)` return the same projection,
+including `rfcMessageId`. Callers must authorize exposing this metadata to their users.
+`EmailEffects`, `EmailEffectOutcome` and `EmailMessageRef` are deprecated internal
+implementation types; consuming qbits use `EmailApi`.
+
+The effect's `SENT` means successful durable handoff, not mailbox delivery. The
+email dispatcher owns later delivery/retry failures. Reconcile acknowledges an
+existing outbox row (including an audit row); it must never create another email
+merely because that row is terminal. Retain message rows and idempotency keys for
+at least the maximum effect retry/reconciliation horizon.
+
+## Register, declare and emit
+
+Enable durable jobs **before** producing the email qbit, so the producer can register
+its target automatically:
+
+```java
+instance.withSupplementalMetaData(new DurableJobsMetaData());
+new DurableJobsMetaDataProvider().defineAll(instance, "rdbms", null);
+new EmailQBitProducer()
+   .withQBitConfig(new EmailQBitConfig().withBackendName("rdbms"))
+   .produce(instance);
+```
+
+Apply core's jobs database schema as usual. `EmailJobEffectTarget.register(instance)`
+is a no-op without `DurableJobsMetaData`. If jobs are enabled after producing email,
+call this helper explicitly after enabling them.
+
+Declare the effect on the process's `DurableProcessMetaData` (retain any existing
+durable settings). Replace `<step>` with the process's real backend step name:
+
+```java
+process.withSupplementalMetaData(new DurableProcessMetaData()
+   .withEffect(new JobEffectDeclaration("welcomeEmail", "<step>", "email",
+      JobEffectType.IDEMPOTENT_EXTERNAL)));
+```
+
+Then emit from that step using its `RunBackendStepInput input` and a stable row key:
+
+```java
+Map<String, Serializable> payload = new LinkedHashMap<>();
+payload.put("to", "person@example.com");
+payload.put("subject", "Welcome");
+payload.put("textBody", "Your account is ready.");
+JobEffects.emit(input, "welcomeEmail", rowKey, payload);
+```
+
+The jobs classes above come from `com.kingsrook.qqq.backend.core.jobs` and its
+`effects` package; `Map`, `LinkedHashMap` and `Serializable` are JDK types.
+Core stores the effect with the chunk's progress and dispatches after commit.
+Outside a durable job, `JobEffects.emit` calls the target immediately with a fresh
+key, still only enqueueing email; a result other than SENT throws.
+
+Use **IDEMPOTENT_EXTERNAL**: qbit-email deduplicates by the effect's exact key,
+while its own delivery outbox reuses the stored Message-ID on provider attempts.
+This acknowledges one durable handoff, not exactly-once delivery to a mailbox.
+
+## Payload contract
+
+Unknown keys are ignored. Recognized values must have the following types:
+
+| Keys | Values |
+|---|---|
+| `to`, `cc`, `bcc` | A String mailbox or a list of String mailboxes; omitted means empty. Comma-separated strings are not split. |
+| `subject`, `templateName` | Strings; ordinary template/ad-hoc validation applies. |
+| `markdownBody`, `htmlBody`, `textBody` | String body alternatives. |
+| `variables` | Map with String keys and serializable values; requires a template schema and retains the normal PHI/classification checks. |
+| `category` | String enum name: `TRANSACTIONAL`, `SECURITY`, `NOTIFICATION`, or `MARKETING`. |
+| `providerName`, `brandName`, `locale` | Strings; omitted locale retains `en`. |
+| `from`, `replyTo` | String mailboxes, subject to ordinary sender validation. |
+| `fromAddressId` | Integer identifying an enabled address for the selected provider. |
+| `sendAfter` | ISO-8601 Instant String, for example `2026-10-14T12:00:00Z`. |
+| `linkedTableName`, `linkedRecordId` | String table name; record id converted to String. |
+
+The target always sets `senderQbit = "jobs"`, `senderProcess = effectName`, and
+uses `EffectRequest.idempotencyKey()`. Payload keys cannot override these or attach
+a transaction. `recordVariables`, `securityValues` and `payloadRef` are not decoded;
+provide the supported values directly in `payload`.
+
+## Identity and outcomes
+
+The dispatcher invokes the target as the system user. When `jobId` is present, the
+target loads the job under core's system scope and builds its owner session through
+`JobSessions.forJob`. Sending runs inside `QContext.withTemporaryContext` using that
+owner session, with current permissions and the intersection of current and captured
+security keys. The original dispatcher context is restored even after an exception.
+Without a job id, sending retains the caller's session.
+
+- `QUEUED_OR_DUPLICATE` becomes `EffectResult.sent(outboxId)`; `providerRef` is the
+  String email row id, not the transport provider's reference.
+- `REFUSED` becomes `EffectResult.failed(reasons)`, including suppressed replays.
+- A missing job or an owner session rejected by authentication/permission validation
+  becomes FAILED with `The job's owner can no longer send it: ...`.
+- Other exceptions, including payload decoding and database failures, become UNKNOWN.
+  Error text omits raw exception details to avoid exposing payloads or database values.
+  Core may resend IDEMPOTENT_EXTERNAL effects using the same key.
+- Reconcile uses `EmailEffects.findByIdempotencyKey`: any existing row becomes FOUND
+  with its id, otherwise NOT_FOUND. Lookup failures propagate rather than falsely
+  reporting absence. Reconcile never creates mail or changes the owner session.
+
+The binding uses `EmailEffects` internally; other consuming qbits continue to use
+`EmailApi`. The H2 target tests install core jobs metadata with `defineAll`, create
+all columns of the `jobs_job` lookup table, and observe the owner through an insert
+customizer because email messages have no built-in created-by/user field. No
+production job-lookup test seam is needed.
+
+Tests use H2, the existing GreenMail SMTP sink, fake SES and HTTP request seams;
+no vendor endpoints are called. The PostgreSQL migration is supplied for host
+deployment and is not executed by the offline Java test gate.

docs/PROVIDERS.md

@@ -0,0 +1,265 @@
+# Email providers
+
+Create an enabled `email_provider` row and choose exactly one enabled default.
+Provider edits and Send Test Email require `email.admin`. Test sends queue through
+the outbox and obey the same rate limits as application messages.
+
+Field names here are database columns. QQQ record/API names are camelCase:
+`secret_env_name` is `secretEnvName`, for example. All kinds use `name`, `label`,
+`kind`, `enabled`, `is_default`, `from_address`, optional `from_name` / `reply_to`,
+and optional `max_per_minute` / `max_per_day`. When set, `sending_domain` must
+match the From address domain exactly.
+
+## Credentials and delivery
+
+Credential fields contain environment variable **names**, never values. Names
+must match `^[A-Z_][A-Z0-9_]{0,99}$` and the effective allowlist. The defaults
+below supplement `EmailQBitConfig.allowedEnvNames`; explicitly allow custom names.
+Allowlisting does not automatically select a name for a row.
+
+| Kind | `username_env_name` | `secret_env_name` | `webhook_secret_env_name` |
+|---|---|---|---|
+| SMTP | `EMAIL_SMTP_USERNAME` (optional) | `EMAIL_SMTP_PASSWORD` | Not used |
+| SES | `AWS_ACCESS_KEY_ID` (optional) | `AWS_SECRET_ACCESS_KEY` (optional pair) | Not used; `sns_topic_arn` is a plain ARN |
+| POSTMARK | Not used | `POSTMARK_SERVER_TOKEN` | `POSTMARK_WEBHOOK_PASSWORD` |
+| SENDGRID | Not used | `SENDGRID_API_KEY` | `SENDGRID_WEBHOOK_PUBLIC_KEY` |
+| MAILGUN | Not used | `MAILGUN_API_KEY` | `MAILGUN_WEBHOOK_SIGNING_KEY` |
+| GMAIL_SMTP | `GMAIL_USERNAME` | `GMAIL_APP_PASSWORD` | Not used |
+
+Legacy `EMAIL_POSTMARK_SERVER_TOKEN`, `EMAIL_POSTMARK_WEBHOOK_PASSWORD`,
+`EMAIL_SENDGRID_API_KEY`, `EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY`, `EMAIL_MAILGUN_API_KEY`,
+`EMAIL_MAILGUN_SIGNING_KEY`, `EMAIL_GMAIL_USERNAME` and `EMAIL_GMAIL_APP_PASSWORD`
+remain allowlisted for their kinds. SES also allowlists `AWS_SESSION_TOKEN` for
+the default credential chain; explicit row credentials are an access/secret pair.
+
+Values resolve through `secretResolver` (default `System::getenv`) for each send
+attempt. Rotation needs no service restart. Provider record presence indicators
+also resolve values, returning only Set / Not set; enqueue and internal queries
+do not resolve credentials. Values and provider response diagnostics are never
+logged, stored in errors, returned in exceptions or cached by these transports.
+
+HTTP uses fixed HTTPS endpoints, a 10-second connect timeout, a 30-second request
+timeout, no redirects and no client retries. The outbox owns retries. MIME and
+multipart bodies are built entirely in memory; services use no filesystem storage.
+
+HTTP 429 and 5xx are transient. Retry-After accepts seconds or an HTTP date;
+the dispatcher caps explicit delays at one hour. Authentication/account failures
+mark the provider UNHEALTHY, stop its remaining deliveries for the dispatch pass,
+and retain messages for retry without consuming their failure budget. Permanent
+message errors become DEAD_LETTER. Exceptions use fixed text and numeric codes;
+stored errors use fixed messages, never response bodies.
+
+Acceptance means SENT, not delivered. Delivery is at least once: a crash after
+acceptance can cause a duplicate. Limits count attempts across replicas in rolling
+minute and 24-hour windows, not recipients or successful deliveries. Leave room
+for retries, recipient quotas and other applications using the same account.
+
+## SMTP
+
+Set `kind=SMTP`, `host`, `port`, and `security=NONE`, `STARTTLS`, or `TLS`. For
+authenticated SMTP, set both credential names; for an unauthenticated relay,
+leave both empty. Authentication requires encryption except for loopback or an
+explicit host `allowPlaintextSmtpAuth` configuration.
+
+Configure the relay's allowed sender domains and route. For public delivery,
+verify the domain with the operator, publish its DKIM and SPF records, and align
+the From domain with DMARC. Update the existing SPF policy rather than adding a
+second SPF record. Set limits below the relay's quota. SMTP has 10-second connect
+and 15-second read/write timeouts; there is no provider event webhook here.
+
+## Amazon SES
+
+Set `kind=SES`, `region`, and a verified `from_address`. Optionally set
+`sending_domain`, `configuration_set` and `sns_topic_arn`. Leave credential names
+empty for the AWS default chain (workload/instance role or AWS environment);
+otherwise supply both access-key and secret-key environment names.
+
+Verify the sender identity in the sending region and publish SES's DKIM records.
+Configure SPF for a custom MAIL FROM domain if used. Request production access
+when leaving the sandbox. Configure the configuration set's SNS event destination
+and put the topic ARN in `sns_topic_arn`, not a secret field.
+
+Sending quotas are regional and account-specific, with sandbox, recipient and
+rate restrictions. Set both rate fields to fit those quotas. SES sends raw MIME
+with explicit envelope destinations and strips Bcc from its MIME headers.
+
+## Postmark
+
+Set `kind=POSTMARK`, `secret_env_name=POSTMARK_SERVER_TOKEN`, a verified
+`from_address`, and optionally `sending_domain`. Use a server token, not an
+account token. `message_stream` defaults to `outbound`; another transactional or
+broadcast stream must exist on that server. `track_opens` and `track_clicks`
+default to false; click tracking maps to HtmlAndText or None.
+
+Verify the domain or sender signature, publish Postmark's DKIM and recommended
+Return-Path/SPF DNS records, obtain account approval and create the desired
+message stream. The endpoint is `https://api.postmarkapp.com/email`;
+the returned `MessageID` is retained.
+
+| Signal | Outcome |
+|---|---|
+| ErrorCode 10 | Provider failure: bad token |
+| ErrorCode 300 / 406 | Permanent: invalid request / inactive recipient |
+| ErrorCode 400/401, 405, 412, 413, 422 | Provider failure: signature, sending approval or server/account configuration |
+| ErrorCode 1235/1236 / 1480 | Provider failure: stream / IP configuration |
+| HTTP 401/403 | Provider failure |
+| HTTP 429 / 5xx | Transient; takes precedence over a body code |
+| Other request errors | Permanent; malformed successful responses are transient |
+
+API ErrorCode 413 is an account problem; HTTP 413 is a payload-size error.
+Check plan, recipient and payload limits before setting the rate fields. The
+single-message API documents a 10 MB message limit. See
+[Postmark API errors and limits](https://postmarkapp.com/developer/api/overview).
+
+## SendGrid
+
+Set `kind=SENDGRID`, `secret_env_name=SENDGRID_API_KEY`, a verified `from_address`
+and optionally `sending_domain`. Create a key with Mail Send permission.
+Authenticate the domain and publish SendGrid's DKIM/SPF DNS records; single-sender
+verification can be used for initial tests. Confirm the account can send.
+
+`track_opens` controls open tracking; `track_clicks` controls HTML and plain-text
+click tracking. Explicit false values override account tracking defaults.
+The global endpoint is `https://api.sendgrid.com/v3/mail/send`; only HTTP 202
+counts as success and `X-Message-Id` becomes the provider message ID.
+
+One personalization contains To/Cc/Bcc with display names. `custom_args` carries
+`qqq_email_id`. Reserved headers are filtered case-insensitively: `x-sg-id`,
+`x-sg-eid`, `received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`,
+`To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`. `List-Unsubscribe` and
+`List-Unsubscribe-Post` are retained.
+
+HTTP 401/403 are provider failures, 400/413 permanent, and 429/5xx transient.
+Set rate limits for the account's plan/API quota. Payload and recipient limits
+apply separately from outbox attempt limits. See
+[SendGrid Mail Send](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send).
+
+## Mailgun
+
+Set `kind=MAILGUN`, `secret_env_name=MAILGUN_API_KEY`, `sending_domain` (required,
+a DNS name without a scheme/path), and `region=US` or `EU` (required).
+The From address domain must match the sending domain.
+
+Add and verify the domain in that region. Publish Mailgun's SPF/DKIM records and
+its requested tracking DNS records if enabling tracking. Use an API key allowed
+to send for that domain. Sandbox domains restrict recipients; check production
+status and plan/rate quotas before choosing `max_per_minute` / `max_per_day`.
+Those fields do not enforce MIME-size or recipient limits.
+
+The endpoint is `https://api.mailgun.net/v3/{sending_domain}/messages.mime`, or
+`https://api.eu.mailgun.net/v3/{sending_domain}/messages.mime` for EU. Basic auth
+uses `api:<resolved key>`. Multipart includes all To/Cc/Bcc mailboxes as envelope
+destinations, MIME `message` with Bcc stripped, `o:tracking-opens`,
+`o:tracking-clicks` (explicit yes/no from the row), and `v:qqq_email_id`.
+The response `id` is stored without surrounding angle brackets.
+
+HTTP 401/403 are provider failures, 400 permanent, and 429/5xx transient.
+
+## Gmail SMTP
+
+| Field | Value |
+|---|---|
+| `kind` | `GMAIL_SMTP` |
+| `username_env_name` | `GMAIL_USERNAME`: value is the full account email address |
+| `secret_env_name` | `GMAIL_APP_PASSWORD`: value is the generated app password |
+| `security` | `STARTTLS` |
+| `from_address` | Account address or a permitted configured alias |
+| `max_per_day` | At most about 500 personal / 2000 paid Workspace; lower with headroom |
+
+The preset always uses `smtp.gmail.com:587` with required STARTTLS, ignoring
+custom host/port values. Both env names are required; other security values are
+refused even if plaintext auth is enabled for other relays. An omitted security
+value uses the preset at the settings layer, but provider forms default to NONE,
+so select STARTTLS when creating the row.
+
+Enable 2-step verification and generate an app password for the service; do not
+use the normal account password. Account/admin security policy may disable app
+passwords. A Google password change revokes existing app passwords, requiring a
+new environment value. See
+[Google app password setup](https://support.google.com/accounts/answer/185833).
+
+Google manages domain authentication for personal gmail.com senders. For
+Workspace, verify the domain and configure Google's SPF/DKIM records and DMARC.
+Trials, new accounts, SMTP recipient quotas and other account users can reduce
+available capacity. The 500/2000 limit is an upper planning bound, not guaranteed
+throughput. See [Workspace limits](https://support.google.com/a/answer/166852)
+and [personal Gmail limits](https://support.google.com/mail/answer/22839).
+
+`GMAIL_API` is refused with:
+`Gmail API sending is specified but not built; use GMAIL_SMTP`.
+It would require a Google Cloud project, OAuth consent, client credentials and
+refresh-token management. It adds no needed system-mail capability over the app
+password preset in this phase and is built only on request (DESIGN 3.6).
+
+## Event webhooks
+
+Phase (c) installs authenticated provider receivers when the host includes Javalin.
+Use `https://<app>{base}/{kind}/{providerName}`, where `base` is
+`EmailQBitConfig.webhookBasePath` (default `/qqq/hooks/email`), `kind` is `ses`,
+`postmark`, `sendgrid` or `mailgun`, and `providerName` is the row's unique name.
+The row must be enabled and its kind must match. The configurable base must start
+with `/`, have no trailing slash, and stay outside `/qqq/v1`.
+
+| Provider | Setup and events |
+|---|---|
+| SES | Send configuration-set Delivery, Bounce, Complaint, Reject and DeliveryDelay events to SNS; enable Open/Click only when desired. Set `sns_topic_arn` to that exact topic. Subscribe the HTTPS `/ses/{providerName}` URL with raw delivery **off**, so SNS sends its signed JSON envelope. No webhook secret env is used. Verified subscription confirmations are fetched automatically and retained as IGNORED inbox rows. |
+| Postmark | Configure server/message-stream webhooks for Delivery, Bounce, SpamComplaint and SubscriptionChange; optionally Open and Click. Use HTTP Basic username **`postmark`** and the password resolved from `webhook_secret_env_name` (normally `POSTMARK_WEBHOOK_PASSWORD`). Configure those credentials in Postmark's webhook settings/URL; keep the stored provider row limited to the environment name. |
+| SendGrid | Enable the Signed Event Webhook for delivered, bounce, dropped, deferred, spamreport and unsubscribe (group_unsubscribe is also accepted); optionally open/click. Store the base64 DER verification public key in `SENDGRID_WEBHOOK_PUBLIC_KEY`, referenced by `webhook_secret_env_name`. Preserve both Twilio signature/timestamp headers through the proxy. Batches are authenticated over timestamp plus the unchanged raw body. |
+| Mailgun | Configure regional domain webhooks for delivered, permanent/temporary failed, complained and unsubscribed; optionally opened/clicked. Set `webhook_secret_env_name=MAILGUN_WEBHOOK_SIGNING_KEY` to the account's HTTP webhook signing key, **not** its sending API key. Preserve the JSON `signature` object and `event-data`. |
+| SMTP / Gmail SMTP | No native event receiver. One-click unsubscribe remains available for opt-out mail. |
+
+SNS accepts SignatureVersion 1 and 2, pins TopicArn, and fetches certificates only
+from HTTPS `sns.<region>.amazonaws.com` or `.amazonaws.com.cn` hosts with `.pem`
+paths. Certificates are cached only in memory; redirects are disabled. Confirmation
+URLs use the same HTTPS host restriction. Canonicalization follows
+[AWS's signature rules](https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message-verify-message-signature.html).
+SNS retries can be old, so freshness is enforced only for SendGrid and Mailgun:
+timestamps must be within five minutes in either direction. Keep host clocks synchronized.
+Postmark authenticates the request with Basic auth and supplies no signed timestamp.
+
+Requests are capped at 1 MiB, including chunked requests. Responses are JSON:
+200 `received` or `duplicate`, 401 invalid verification/Mailgun nonce replay,
+404 missing/disabled/mismatched provider, 413 oversized input, and 503 unavailable
+verification configuration, SNS fetch or database. No request bodies, recipient
+addresses or credential values are logged. Raw payloads are stored in the DB inbox
+as sensitive data, readable with `email.view`.
+
+The hidden `email_process_webhooks` schedule runs every 30 seconds. One bounded
+transaction applies each inbox row, including events, message state and suppressions.
+The common provider lock serializes suppression upserts across replicas/providers;
+no network I/O occurs under that lock. Failed attempts back off with `retryMinutes`
+and become FAILED after six attempts. Use the inbox's **Reprocess** Review/Result
+action (`email.manage`) after resolving the cause. Unmatched messages retry, including
+a webhook racing the transport's SENT commit. Unknown/disabled tracking events are
+IGNORED. Per-event recipient keys prevent overlapping SendGrid batches from duplicating
+history. Mailgun's `(provider_id, nonce)` uniqueness is distinct from event deduplication:
+a stored nonce is refused with 401 even if its event is already known.
+
+Hard bounces and complaints upsert ALL suppression; complaints take precedence over
+hard-bounce reasons. Unsubscribe events suppress only MARKETING or NOTIFICATION for
+the matched message. Delivery advances SENT to DELIVERED; hard bounce and complaint
+advance delivery state without reversing a later complaint. Opens/clicks require the
+corresponding provider flag and are never retained for PHI-approved messages.
+Provider reason text is address-masked and limited to 500 characters; only clicks
+retain URLs. More than three complaints in 24 hours raises optional WARNING alert
+`email.complaint`, deduplicated per UTC day by core's alert sink.
+
+## One-click unsubscribe
+
+Set `publicBaseUrl` to the public HTTPS app origin and supply
+`QQQ_EMAIL_UNSUBSCRIBE_KEY` through the secret resolver. The configured webhook base
+also controls newly signed unsubscribe URLs. Keep the key and published path stable:
+tokens have no expiry, but cannot resolve after their message row is deleted.
+
+GET `{base}/unsubscribe/{token}` displays a self-contained, escaped light/dark form
+and never changes state. POST `List-Unsubscribe=One-Click` returns an empty 200;
+the page's form POST returns confirmation HTML. Both atomically upsert category
+suppression and record an UNSUBSCRIBED event. Repeated POSTs do not duplicate events.
+Invalid tokens return a generic 404. TRANSACTIONAL and SECURITY tokens are neither
+issued nor accepted.
+
+The existing v1 token binds the message, category and **complete To/Cc/Bcc envelope
+hash**, rather than one mailbox. Following that link opts out every mailbox in the
+bound envelope for that category; the page reveals none of those addresses. Send
+one recipient per opt-out message when individual preference control is needed.
+Preferences UI remains deferred until core #1162 ships in an RC.

docs/ddl/email-foreign-keys-upgrade.sql

@@ -0,0 +1,89 @@
+-- qbit-email: add the foreign keys to an existing PostgreSQL schema (one
+-- created from email-postgres.sql before they were declared there). Pause
+-- enqueue, dispatch and webhook processing while it runs.
+--
+-- Safe to run more than once: a foreign key that already exists with the
+-- right ON DELETE (under any name) is left alone. Before each key is added,
+-- rows that point at a missing parent are recorded in qqq_fk_quarantine and
+-- then set to NULL (nullable column) or deleted (NOT NULL column; the whole
+-- row is kept in row_data). An existing key on the column with a different
+-- ON DELETE is replaced by the named one.
+--
+-- Order matters: sender addresses, attempts and events of a missing parent are
+-- removed before the references to them (message.from_address_id,
+-- suppression.source_event_id) are checked.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS qqq_fk_quarantine (id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, table_name VARCHAR(100) NOT NULL, column_name VARCHAR(100) NOT NULL, row_id VARCHAR(100), missing_parent_id VARCHAR(100), action VARCHAR(20) NOT NULL, row_data TEXT, changeset VARCHAR(200), quarantined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);
+
+CREATE OR REPLACE FUNCTION pg_temp.qqq_add_fk(p_table TEXT, p_column TEXT, p_parent TEXT, p_on_delete TEXT) RETURNS VOID LANGUAGE plpgsql AS
+$fn$
+DECLARE
+   v_name      TEXT    := 'fk_' || p_table || '_' || p_column;
+   v_rule      "char"  := CASE p_on_delete WHEN 'CASCADE' THEN 'c' WHEN 'SET NULL' THEN 'n' WHEN 'RESTRICT' THEN 'r' ELSE 'a' END;
+   v_nullable  BOOLEAN;
+   v_changeset TEXT    := 'qbit-email:email-foreign-keys-upgrade.sql';
+   v_old       RECORD;
+BEGIN
+   IF EXISTS (SELECT 1 FROM pg_constraint c JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+              WHERE c.contype = 'f' AND c.conrelid = p_table::regclass AND cardinality(c.conkey) = 1 AND a.attname = p_column
+                AND c.confrelid = p_parent::regclass AND c.confdeltype = v_rule) THEN
+      RETURN;
+   END IF;
+
+   FOR v_old IN SELECT c.conname FROM pg_constraint c JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+                WHERE c.contype = 'f' AND c.conrelid = p_table::regclass AND cardinality(c.conkey) = 1 AND a.attname = p_column LOOP
+      EXECUTE format('ALTER TABLE %I DROP CONSTRAINT %I', p_table, v_old.conname);
+   END LOOP;
+
+   SELECT is_nullable = 'YES' INTO v_nullable FROM information_schema.columns
+   WHERE table_schema = current_schema() AND table_name = p_table AND column_name = p_column;
+
+   IF v_nullable THEN
+      EXECUTE format('INSERT INTO qqq_fk_quarantine (table_name, column_name, row_id, missing_parent_id, action, changeset) '
+         || 'SELECT %L, %L, t.id::TEXT, t.%I::TEXT, ''NULLED'', %L FROM %I t WHERE t.%I IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = t.%I)',
+         p_table, p_column, p_column, v_changeset, p_table, p_column, p_parent, p_column);
+      EXECUTE format('UPDATE %I t SET %I = NULL WHERE t.%I IS NOT NULL AND NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = t.%I)',
+         p_table, p_column, p_column, p_parent, p_column);
+   ELSE
+      EXECUTE format('INSERT INTO qqq_fk_quarantine (table_name, column_name, row_id, missing_parent_id, action, row_data, changeset) '
+         || 'SELECT %L, %L, t.id::TEXT, t.%I::TEXT, ''DELETED'', row_to_json(t)::TEXT, %L FROM %I t WHERE NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = t.%I)',
+         p_table, p_column, p_column, v_changeset, p_table, p_parent, p_column);
+      EXECUTE format('DELETE FROM %I t WHERE NOT EXISTS (SELECT 1 FROM %I p WHERE p.id = t.%I)', p_table, p_parent, p_column);
+   END IF;
+
+   EXECUTE format('ALTER TABLE %I ADD CONSTRAINT %I FOREIGN KEY (%I) REFERENCES %I (id) ON DELETE %s', p_table, v_name, p_column, p_parent, p_on_delete);
+END
+$fn$;
+
+SELECT pg_temp.qqq_add_fk('email_provider_sender_address', 'provider_id', 'email_provider', 'CASCADE');
+SELECT pg_temp.qqq_add_fk('email_message', 'provider_id', 'email_provider', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_message', 'from_address_id', 'email_provider_sender_address', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_message', 'template_id', 'email_template', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_message', 'template_version_id', 'email_template_version', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_message', 'brand_id', 'email_brand', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_template', 'brand_id', 'email_brand', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_template', 'active_version_id', 'email_template_version', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_template', 'approved_version_id', 'email_template_version', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_template_version', 'template_id', 'email_template', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_message_attempt', 'message_id', 'email_message', 'CASCADE');
+SELECT pg_temp.qqq_add_fk('email_message_attempt', 'provider_id', 'email_provider', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_event', 'message_id', 'email_message', 'CASCADE');
+SELECT pg_temp.qqq_add_fk('email_event', 'provider_id', 'email_provider', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_webhook_inbox', 'provider_id', 'email_provider', 'RESTRICT');
+SELECT pg_temp.qqq_add_fk('email_suppression', 'source_message_id', 'email_message', 'SET NULL');
+SELECT pg_temp.qqq_add_fk('email_suppression', 'source_event_id', 'email_event', 'SET NULL');
+
+CREATE INDEX IF NOT EXISTS email_message_from_address ON email_message (from_address_id);
+CREATE INDEX IF NOT EXISTS email_message_template ON email_message (template_id);
+CREATE INDEX IF NOT EXISTS email_message_template_version ON email_message (template_version_id);
+CREATE INDEX IF NOT EXISTS email_message_brand ON email_message (brand_id);
+CREATE INDEX IF NOT EXISTS email_template_brand ON email_template (brand_id);
+CREATE INDEX IF NOT EXISTS email_template_active_version ON email_template (active_version_id);
+CREATE INDEX IF NOT EXISTS email_template_approved_version ON email_template (approved_version_id);
+CREATE INDEX IF NOT EXISTS email_suppression_source_message ON email_suppression (source_message_id);
+CREATE INDEX IF NOT EXISTS email_suppression_source_event ON email_suppression (source_event_id);
+CREATE INDEX IF NOT EXISTS email_event_provider ON email_event (provider_id);
+
+COMMIT;

docs/ddl/email-message-id-upgrade.sql

@@ -0,0 +1,11 @@
+-- Existing PostgreSQL installations: pause enqueue and dispatch before applying.
+-- SHA-256 is PostgreSQL's built-in bytea function; no extension is required.
+BEGIN;
+ALTER TABLE email_message ADD COLUMN rfc_message_id VARCHAR(500);
+UPDATE email_message
+SET rfc_message_id = '<' || left(encode(sha256(convert_to(
+   coalesce(idempotency_key, 'qbit-email:' || id::text), 'UTF8')), 'hex'), 32)
+   || '@' || coalesce(lower(substring(from_address from
+      '@([A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*)(?:>|$)')), 'qbit-email.local') || '>';
+ALTER TABLE email_message ADD CONSTRAINT email_message_rfc_message_id_unique UNIQUE (rfc_message_id);
+COMMIT;

docs/ddl/email-postgres.sql

@@ -1,4 +1,4 @@
--- Phase (a), part 1. Apply before producing the qbit. Host security columns must be added by the host.
+-- Phases (a), (b) and (c). Apply before producing the qbit. Host security columns must be added by the host.
 
 CREATE TABLE email_provider (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
@@ -38,6 +38,19 @@ CREATE TABLE email_provider (
    UNIQUE (default_slot)
 );
 
+CREATE TABLE email_provider_sender_address (
+   id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   create_date TIMESTAMP,
+   modify_date TIMESTAMP,
+   provider_id INTEGER NOT NULL,
+   address VARCHAR(500) NOT NULL,
+   display_name VARCHAR(500),
+   is_default BOOLEAN,
+   enabled BOOLEAN,
+   note TEXT,
+   UNIQUE (provider_id, address)
+);
+
 CREATE TABLE email_message (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    create_date TIMESTAMP,
@@ -47,6 +60,7 @@ CREATE TABLE email_message (
    cc_addresses TEXT,
    bcc_addresses TEXT,
    from_address VARCHAR(500),
+   from_address_id INTEGER,
    reply_to VARCHAR(500),
    subject TEXT,
    template_id INTEGER,
@@ -58,7 +72,10 @@ CREATE TABLE email_message (
    html_body TEXT,
    text_body TEXT,
    body_sha256 VARCHAR(500),
+   phi_approved BOOLEAN,
+   unsubscribe_url TEXT,
    idempotency_key VARCHAR(500),
+   rfc_message_id VARCHAR(500),
    provider_id INTEGER,
    provider_message_id VARCHAR(500),
    attempt_count INTEGER,
@@ -68,6 +85,8 @@ CREATE TABLE email_message (
    finished_date TIMESTAMP,
    sent_date TIMESTAMP,
    delivered_date TIMESTAMP,
+   bounced_date TIMESTAMP,
+   complained_date TIMESTAMP,
    dead_letter_date TIMESTAMP,
    linked_table_name VARCHAR(500),
    linked_record_id VARCHAR(500),
@@ -75,7 +94,8 @@ CREATE TABLE email_message (
    sender_process VARCHAR(500),
    suppressed_addresses TEXT,
    send_after TIMESTAMP,
-   UNIQUE (idempotency_key)
+   UNIQUE (idempotency_key),
+   UNIQUE (rfc_message_id)
 );
 
 CREATE TABLE email_message_attempt (
@@ -105,6 +125,8 @@ CREATE TABLE email_template (
    kind VARCHAR(500),
    brand_id INTEGER,
    active_version_id INTEGER,
+   approved_version_id INTEGER,
+   version_lock INTEGER,
    phi_approved BOOLEAN,
    phi_approved_by VARCHAR(500),
    phi_approved_date TIMESTAMP,
@@ -148,6 +170,8 @@ CREATE TABLE email_brand (
    background_color VARCHAR(500),
    dark_background_color VARCHAR(500),
    dark_text_color VARCHAR(500),
+   dark_primary_color VARCHAR(500),
+   dark_button_text_color VARCHAR(500),
    button_text_color VARCHAR(500),
    footer_markdown TEXT,
    postal_address TEXT,
@@ -176,3 +200,81 @@ CREATE TABLE email_suppression (
 CREATE INDEX email_message_due ON email_message (status, next_attempt_date);
 CREATE INDEX email_attempt_provider_start ON email_message_attempt (provider_id, start_date);
 CREATE INDEX email_attempt_provider_end ON email_message_attempt (provider_id, end_date, id);
+
+CREATE TABLE email_webhook_inbox (
+   id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   create_date TIMESTAMP,
+   modify_date TIMESTAMP,
+   provider_id INTEGER NOT NULL,
+   kind VARCHAR(500) NOT NULL,
+   external_event_id VARCHAR(500) NOT NULL,
+   nonce VARCHAR(500),
+   status VARCHAR(500) NOT NULL,
+   attempts INTEGER NOT NULL DEFAULT 0,
+   next_attempt_date TIMESTAMP,
+   last_error VARCHAR(500),
+   payload_json TEXT,
+   payload_sha256 VARCHAR(500),
+   received_date TIMESTAMP,
+   processed_date TIMESTAMP,
+   UNIQUE (provider_id, external_event_id),
+   UNIQUE (provider_id, nonce)
+);
+
+CREATE TABLE email_event (
+   id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   create_date TIMESTAMP,
+   modify_date TIMESTAMP,
+   message_id INTEGER NOT NULL,
+   provider_id INTEGER,
+   event_type VARCHAR(500) NOT NULL,
+   bounce_type VARCHAR(500),
+   recipient VARCHAR(500),
+   occurred_date TIMESTAMP,
+   detail VARCHAR(500),
+   url TEXT,
+   event_key VARCHAR(500) NOT NULL UNIQUE
+);
+CREATE INDEX email_inbox_due ON email_webhook_inbox (status, next_attempt_date);
+CREATE INDEX email_event_message ON email_event (message_id);
+CREATE INDEX email_event_type_date ON email_event (event_type, occurred_date);
+CREATE INDEX email_message_provider_id ON email_message (provider_id, provider_message_id);
+
+-- Foreign keys (named fk_<table>_<column>), added after every table exists.
+--   CASCADE   owned rows: a provider's sender addresses (the provider delete also removes
+--             them), a message's attempts and events (message retention deletes them first).
+--   RESTRICT  configuration under live data: providers with messages, attempts, events or
+--             webhook inbox rows (disable the provider instead); a brand used by a template;
+--             a template with versions (templates with versions cannot be deleted).
+--   SET NULL  optional pointers: a message's sender address, template, version and brand
+--             (the rendered body is kept); a template's active/approved version (the
+--             cycle with email_template_version.template_id; drafts can be deleted); a
+--             suppression's source message and event, which outlive message retention.
+-- Existing databases: run email-foreign-keys-upgrade.sql.
+ALTER TABLE email_provider_sender_address ADD CONSTRAINT fk_email_provider_sender_address_provider_id FOREIGN KEY (provider_id) REFERENCES email_provider (id) ON DELETE CASCADE;
+ALTER TABLE email_message ADD CONSTRAINT fk_email_message_provider_id FOREIGN KEY (provider_id) REFERENCES email_provider (id) ON DELETE RESTRICT;
+ALTER TABLE email_message ADD CONSTRAINT fk_email_message_from_address_id FOREIGN KEY (from_address_id) REFERENCES email_provider_sender_address (id) ON DELETE SET NULL;
+ALTER TABLE email_message ADD CONSTRAINT fk_email_message_template_id FOREIGN KEY (template_id) REFERENCES email_template (id) ON DELETE SET NULL;
+ALTER TABLE email_message ADD CONSTRAINT fk_email_message_template_version_id FOREIGN KEY (template_version_id) REFERENCES email_template_version (id) ON DELETE SET NULL;
+ALTER TABLE email_message ADD CONSTRAINT fk_email_message_brand_id FOREIGN KEY (brand_id) REFERENCES email_brand (id) ON DELETE SET NULL;
+ALTER TABLE email_message_attempt ADD CONSTRAINT fk_email_message_attempt_message_id FOREIGN KEY (message_id) REFERENCES email_message (id) ON DELETE CASCADE;
+ALTER TABLE email_message_attempt ADD CONSTRAINT fk_email_message_attempt_provider_id FOREIGN KEY (provider_id) REFERENCES email_provider (id) ON DELETE RESTRICT;
+ALTER TABLE email_template ADD CONSTRAINT fk_email_template_brand_id FOREIGN KEY (brand_id) REFERENCES email_brand (id) ON DELETE RESTRICT;
+ALTER TABLE email_template ADD CONSTRAINT fk_email_template_active_version_id FOREIGN KEY (active_version_id) REFERENCES email_template_version (id) ON DELETE SET NULL;
+ALTER TABLE email_template ADD CONSTRAINT fk_email_template_approved_version_id FOREIGN KEY (approved_version_id) REFERENCES email_template_version (id) ON DELETE SET NULL;
+ALTER TABLE email_template_version ADD CONSTRAINT fk_email_template_version_template_id FOREIGN KEY (template_id) REFERENCES email_template (id) ON DELETE RESTRICT;
+ALTER TABLE email_suppression ADD CONSTRAINT fk_email_suppression_source_message_id FOREIGN KEY (source_message_id) REFERENCES email_message (id) ON DELETE SET NULL;
+ALTER TABLE email_suppression ADD CONSTRAINT fk_email_suppression_source_event_id FOREIGN KEY (source_event_id) REFERENCES email_event (id) ON DELETE SET NULL;
+ALTER TABLE email_webhook_inbox ADD CONSTRAINT fk_email_webhook_inbox_provider_id FOREIGN KEY (provider_id) REFERENCES email_provider (id) ON DELETE RESTRICT;
+ALTER TABLE email_event ADD CONSTRAINT fk_email_event_message_id FOREIGN KEY (message_id) REFERENCES email_message (id) ON DELETE CASCADE;
+ALTER TABLE email_event ADD CONSTRAINT fk_email_event_provider_id FOREIGN KEY (provider_id) REFERENCES email_provider (id) ON DELETE RESTRICT;
+CREATE INDEX email_message_from_address ON email_message (from_address_id);
+CREATE INDEX email_message_template ON email_message (template_id);
+CREATE INDEX email_message_template_version ON email_message (template_version_id);
+CREATE INDEX email_message_brand ON email_message (brand_id);
+CREATE INDEX email_template_brand ON email_template (brand_id);
+CREATE INDEX email_template_active_version ON email_template (active_version_id);
+CREATE INDEX email_template_approved_version ON email_template (approved_version_id);
+CREATE INDEX email_suppression_source_message ON email_suppression (source_message_id);
+CREATE INDEX email_suppression_source_event ON email_suppression (source_event_id);
+CREATE INDEX email_event_provider ON email_event (provider_id);

pom.xml

@@ -22,7 +22,7 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
    <properties>
-      <revision>0.1.0-SNAPSHOT</revision>
+      <revision>0.2.0-SNAPSHOT</revision>
       <maven.compiler.source>21</maven.compiler.source>
       <maven.compiler.target>21</maven.compiler.target>
       <jacoco.version>0.8.15</jacoco.version>
@@ -35,7 +35,7 @@
    <parent>
       <groupId>com.kingsrook</groupId>
       <artifactId>qbit-build-parent</artifactId>
-      <version>2.0.0</version>
+      <version>2.2.1</version>
    </parent>
 
    <groupId>com.kingsrook.qbits</groupId>
@@ -116,6 +116,12 @@
          <artifactId>qqq-backend-module-rdbms</artifactId>
          <scope>test</scope>
       </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-frontend-next</artifactId>
+         <version>1.0.0-RC.38</version>
+         <scope>test</scope>
+      </dependency>
       <dependency>
          <groupId>com.icegreen</groupId>
          <artifactId>greenmail-junit5</artifactId>
@@ -128,6 +134,26 @@
          <version>${h2.version}</version>
          <scope>test</scope>
       </dependency>
+      <!-- the foreign key guardrail test: docs/ddl on a real PostgreSQL (src/test only) -->
+      <dependency>
+         <groupId>org.postgresql</groupId>
+         <artifactId>postgresql</artifactId>
+         <version>42.7.9</version>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.testcontainers</groupId>
+         <artifactId>testcontainers-postgresql</artifactId>
+         <version>2.0.3</version>
+         <scope>test</scope>
+      </dependency>
+      <!-- EmailDefaultsChangelogTest runs the shipped seed changelog through real Liquibase on H2. -->
+      <dependency>
+         <groupId>org.liquibase</groupId>
+         <artifactId>liquibase-core</artifactId>
+         <version>4.33.0</version>
+         <scope>test</scope>
+      </dependency>
       <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter</artifactId>
@@ -142,7 +168,35 @@
    </dependencies>
 
    <build>
+      <resources>
+         <!-- help bundles carry the artifact version (QQQ help bundle provenance) -->
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+            <includes>
+               <include>help/*.yaml</include>
+               <include>qbit-email.properties</include>
+            </includes>
+         </resource>
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>false</filtering>
+            <excludes>
+               <exclude>help/*.yaml</exclude>
+               <exclude>qbit-email.properties</exclude>
+            </excludes>
+         </resource>
+      </resources>
       <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <systemPropertyVariables combine.children="append">
+                  <qbit.artifactVersion>${project.version}</qbit.artifactVersion>
+               </systemPropertyVariables>
+            </configuration>
+         </plugin>
          <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-checkstyle-plugin</artifactId>
@@ -162,7 +216,7 @@
                <failsOnError>false</failsOnError>
                <failOnViolation>true</failOnViolation>
                <violationSeverity>warning</violationSeverity>
-               <includeTestSourceDirectory>false</includeTestSourceDirectory>
+               <includeTestSourceDirectory>true</includeTestSourceDirectory>
             </configuration>
             <executions>
                <execution>
@@ -178,6 +232,11 @@
             <groupId>org.jacoco</groupId>
             <artifactId>jacoco-maven-plugin</artifactId>
             <version>${jacoco.version}</version>
+            <configuration>
+               <excludes>
+                  <exclude>com/kingsrook/qbits/email/demo/**</exclude>
+               </excludes>
+            </configuration>
             <executions>
                <execution>
                   <id>prepare-agent</id>
@@ -230,7 +289,7 @@
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.5</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.25</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/email/EmailQBitConfig.java

@@ -39,9 +39,14 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
  *******************************************************************************/
 public class EmailQBitConfig implements QBitConfig
 {
+   private com.kingsrook.qbits.email.template.MjmlCompilerInterface mjmlCompiler;
+   private java.util.Map<String, com.kingsrook.qbits.email.phi.EmailClassifications.Level> classificationOverrides = java.util.Map.of();
+   private java.util.function.Supplier<com.kingsrook.qbits.email.transport.EmailTransportRegistry> transportRegistryFactory = com.kingsrook.qbits.email.transport.EmailTransportRegistry::new;
+   private Set<String> allowedImageHosts = Set.of();
    private String backendName;
    private String schedulerName;
    private String publicBaseUrl;
+   private String webhookBasePath = "/qqq/hooks/email";
    private String defaultProviderName;
    private String bridgeProviderName = "qbitEmail";
    private Function<String, String> secretResolver = System::getenv;
@@ -54,12 +59,30 @@ public class EmailQBitConfig implements QBitConfig
    private Integer leaseSeconds = 120;
    private Integer bodyRetentionDays = 30;
    private Integer messageRetentionDays = 0;
+   private String templatePermissionBaseName;
    private String appName = "email";
    private String appLabel = "Email";
    private List<QFieldMetaData> securityFields = List.of();
    private List<RecordSecurityLock> recordSecurityLocks = List.of();
    private MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer;
 
+   /*******************************************************************************
+    ** Optional host permission base for template reads/writes only.
+    *******************************************************************************/
+   public String getTemplatePermissionBaseName()
+   {
+      return (templatePermissionBaseName);
+   }
+
+   /*******************************************************************************
+    ** Grant no provider, delivery, PHI approval or other email settings access.
+    *******************************************************************************/
+   public EmailQBitConfig withTemplatePermissionBaseName(String templatePermissionBaseName)
+   {
+      this.templatePermissionBaseName = templatePermissionBaseName;
+      return (this);
+   }
+
    public static final Pattern ENV_NAME = Pattern.compile("^[A-Z_][A-Z0-9_]{0,99}$");
 
    /*******************************************************************************
@@ -85,6 +108,11 @@ public class EmailQBitConfig implements QBitConfig
    @Override
    public void validate(QInstance instance, List<String> errors)
    {
+      if(webhookBasePath == null || !webhookBasePath.matches("/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+")
+         || webhookBasePath.equals("/qqq/v1") || webhookBasePath.startsWith("/qqq/v1/"))
+      {
+         errors.add("webhookBasePath must be an absolute path outside /qqq/v1, without a trailing slash");
+      }
       if(backendName == null || backendName.isBlank())
       {
          errors.add("backendName is required");
@@ -139,11 +167,11 @@ public class EmailQBitConfig implements QBitConfig
       Set<String> names = new HashSet<>(allowedEnvNames);
       names.addAll(switch(kind == null ? "" : kind)
       {
-         case "SMTP", "GMAIL_SMTP" -> Set.of("EMAIL_SMTP_USERNAME", "EMAIL_SMTP_PASSWORD", "EMAIL_GMAIL_USERNAME", "EMAIL_GMAIL_APP_PASSWORD");
+         case "SMTP", "GMAIL_SMTP" -> Set.of("EMAIL_SMTP_USERNAME", "EMAIL_SMTP_PASSWORD", "EMAIL_GMAIL_USERNAME", "EMAIL_GMAIL_APP_PASSWORD", "GMAIL_USERNAME", "GMAIL_APP_PASSWORD");
          case "SES" -> Set.of("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN");
-         case "POSTMARK" -> Set.of("EMAIL_POSTMARK_SERVER_TOKEN", "EMAIL_POSTMARK_WEBHOOK_PASSWORD");
-         case "SENDGRID" -> Set.of("EMAIL_SENDGRID_API_KEY", "EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY");
-         case "MAILGUN" -> Set.of("EMAIL_MAILGUN_API_KEY", "EMAIL_MAILGUN_SIGNING_KEY");
+         case "POSTMARK" -> Set.of("EMAIL_POSTMARK_SERVER_TOKEN", "EMAIL_POSTMARK_WEBHOOK_PASSWORD", "POSTMARK_SERVER_TOKEN", "POSTMARK_WEBHOOK_PASSWORD");
+         case "SENDGRID" -> Set.of("EMAIL_SENDGRID_API_KEY", "EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY", "SENDGRID_API_KEY", "SENDGRID_WEBHOOK_PUBLIC_KEY");
+         case "MAILGUN" -> Set.of("EMAIL_MAILGUN_API_KEY", "EMAIL_MAILGUN_SIGNING_KEY", "MAILGUN_API_KEY", "MAILGUN_WEBHOOK_SIGNING_KEY");
          case "GMAIL_API" -> Set.of("EMAIL_GMAIL_CLIENT_ID", "EMAIL_GMAIL_CLIENT_SECRET", "EMAIL_GMAIL_REFRESH_TOKEN");
          default -> Set.of();
       });
@@ -197,6 +225,23 @@ public class EmailQBitConfig implements QBitConfig
       return (publicBaseUrl);
    }
 
+   /*******************************************************************************
+    ** Public provider and unsubscribe route base.
+    *******************************************************************************/
+   public String getWebhookBasePath()
+   {
+      return (webhookBasePath);
+   }
+
+   /*******************************************************************************
+    ** Configure the route base and queue-time unsubscribe URLs together.
+    *******************************************************************************/
+   public EmailQBitConfig withWebhookBasePath(String webhookBasePath)
+   {
+      this.webhookBasePath = webhookBasePath;
+      return (this);
+   }
+
 
    /*******************************************************************************
     ** Fluent setter for publicBaseUrl.
@@ -510,4 +555,73 @@ public class EmailQBitConfig implements QBitConfig
       this.tableMetaDataCustomizer = tableMetaDataCustomizer;
       return (this);
    }
+
+   /*******************************************************************************
+    ** Activation-time compiler, optional unless MJML templates are used.
+    *******************************************************************************/
+   public com.kingsrook.qbits.email.template.MjmlCompilerInterface getMjmlCompiler()
+   {
+      return (mjmlCompiler);
+   }
+
+   /*******************************************************************************
+    ** Configure a compiler without introducing a runtime dependency.
+    *******************************************************************************/
+   public EmailQBitConfig withMjmlCompiler(com.kingsrook.qbits.email.template.MjmlCompilerInterface compiler)
+   {
+      mjmlCompiler = compiler;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Field classifications used until core supplies classification metadata.
+    *******************************************************************************/
+   public java.util.Map<String, com.kingsrook.qbits.email.phi.EmailClassifications.Level> getClassificationOverrides()
+   {
+      return (classificationOverrides);
+   }
+
+   /*******************************************************************************
+    ** Configure explicit table.field classifications.
+    *******************************************************************************/
+   public EmailQBitConfig withClassificationOverrides(java.util.Map<String, com.kingsrook.qbits.email.phi.EmailClassifications.Level> overrides)
+   {
+      classificationOverrides = java.util.Map.copyOf(overrides);
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Additional HTTPS image hosts permitted for approved email content.
+    *******************************************************************************/
+   public Set<String> getAllowedImageHosts()
+   {
+      return (allowedImageHosts);
+   }
+
+   /*******************************************************************************
+    ** Configure exact host names, without wildcards or URL paths.
+    *******************************************************************************/
+   public EmailQBitConfig withAllowedImageHosts(Set<String> hosts)
+   {
+      allowedImageHosts = hosts.stream().map(host -> host.toLowerCase(java.util.Locale.ROOT)).collect(java.util.stream.Collectors.toUnmodifiableSet());
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Fresh transports for every dispatcher, including process actions.
+    *******************************************************************************/
+   public com.kingsrook.qbits.email.transport.EmailTransportRegistry newTransportRegistry()
+   {
+      return (transportRegistryFactory.get());
+   }
+
+   /*******************************************************************************
+    ** Host-scoped transport injection for embedded applications and local demos.
+    *******************************************************************************/
+   public EmailQBitConfig withTransportRegistryFactory(java.util.function.Supplier<com.kingsrook.qbits.email.transport.EmailTransportRegistry> factory)
+   {
+      transportRegistryFactory = java.util.Objects.requireNonNull(factory);
+      return (this);
+   }
+
 }

src/main/java/com/kingsrook/qbits/email/EmailQBitProducer.java

@@ -21,13 +21,17 @@
 package com.kingsrook.qbits.email;
 
 
+import java.io.IOException;
+import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Properties;
 import com.kingsrook.qbits.email.app.EmailApp;
 import com.kingsrook.qbits.email.bridge.EmailOutboxMessagingProviderMetaData;
 import com.kingsrook.qbits.email.delivery.EmailAlerts;
+import com.kingsrook.qbits.email.health.EmailHealthChecks;
 import com.kingsrook.qbits.email.metadata.EmailTableCustomizers;
 import com.kingsrook.qbits.email.metadata.EmailTables;
 import com.kingsrook.qbits.email.processes.EmailProcesses;
@@ -38,6 +42,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QVirtualFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSectionAlternativeType;
@@ -51,13 +56,41 @@ public class EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>
 {
    public static final String GROUP_ID    = "com.kingsrook.qbits";
    public static final String ARTIFACT_ID = "qbit-email";
-   public static final String VERSION     = "0.1.0";
+   public static final String VERSION     = loadVersion();
 
    private EmailQBitConfig qBitConfig;
    private String          namespace;
 
 
 
+   /*******************************************************************************
+    ** Read the artifact version from the Maven-filtered resource.
+    *******************************************************************************/
+   private static String loadVersion()
+   {
+      try(InputStream inputStream = EmailQBitProducer.class.getClassLoader().getResourceAsStream("qbit-email.properties"))
+      {
+         if(inputStream == null)
+         {
+            throw new IllegalStateException("Missing qbit-email.properties; build with Maven to generate the artifact version");
+         }
+         Properties properties = new Properties();
+         properties.load(inputStream);
+         String version = properties.getProperty("version");
+         if(version == null || version.isBlank() || version.contains("${"))
+         {
+            throw new IllegalStateException("Missing or unfiltered version in qbit-email.properties; build with Maven");
+         }
+         return (version);
+      }
+      catch(IOException e)
+      {
+         throw new IllegalStateException("Could not read artifact version from qbit-email.properties", e);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Fluent setter for the config.
     *******************************************************************************/
@@ -143,7 +176,9 @@ public class EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>
       for(QTableMetaData table : EmailTables.tables(qBitConfig))
       {
          Class<?> customizer = EmailTables.PROVIDER.equals(table.getName()) ? EmailTableCustomizers.ProviderCustomizer.class
-            : EmailTables.SUPPRESSION.equals(table.getName()) ? EmailTableCustomizers.SuppressionCustomizer.class : null;
+            : EmailTables.SENDER.equals(table.getName()) ? EmailTableCustomizers.SenderAddressCustomizer.class
+            : EmailTables.SUPPRESSION.equals(table.getName()) ? EmailTableCustomizers.SuppressionCustomizer.class
+            : List.of(EmailTables.TEMPLATE, EmailTables.VERSION, EmailTables.BRAND).contains(table.getName()) ? com.kingsrook.qbits.email.template.EmailTemplateCustomizers.class : null;
          if(customizer != null)
          {
             table.withCustomizer(TableCustomizers.PRE_INSERT_RECORD, new QCodeReference(customizer))
@@ -154,6 +189,10 @@ public class EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>
          {
             table.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(EmailTableCustomizers.MessageLinksCustomizer.class));
          }
+         if(EmailTables.VERSION.equals(table.getName()))
+         {
+            table.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(com.kingsrook.qbits.email.template.EmailVersionLabels.class));
+         }
          if(EmailTables.PROVIDER.equals(table.getName()))
          {
             table.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(EmailTableCustomizers.ProviderCustomizer.class));
@@ -190,6 +229,31 @@ public class EmailQBitProducer implements QBitMetaDataProducer<EmailQBitConfig>
       output.add(EmailApp.app(qBitConfig, tables));
       output.add(new EmailOutboxMessagingProviderMetaData().withName(qBitConfig.getBridgeProviderName()));
       output.addSelfToInstance(qInstance);
+      EmailHealthChecks.register(qInstance);
+      // Registration is metadata-only; core's startup sync guards hosts without helpContent.
+      HelpBundles.register(qInstance, "help/qbit-email.yaml");
+      HelpBundles.of(qInstance).getBundles().stream().filter(bundle -> "qbit-email".equals(bundle.getId()))
+         .flatMap(bundle -> bundle.getEntries().stream()).filter(entry -> "app:email;slot:help".equals(entry.getKey()))
+         .forEach(entry -> entry.setKey("app:" + qBitConfig.getAppName() + ";slot:help"));
+      registerWebhooks(qInstance);
+      com.kingsrook.qbits.email.outbox.EmailJobEffectTarget.register(qInstance);
       return (new MetaDataProducerMultiOutput());
    }
+
+   /*******************************************************************************
+    ** Keep optional provided middleware linkage outside non-web applications.
+    *******************************************************************************/
+   private static void registerWebhooks(QInstance instance) throws QException
+   {
+      try
+      {
+         Class.forName("io.javalin.Javalin");
+         Class.forName("com.kingsrook.qqq.middleware.javalin.QJavalinMetaData");
+      }
+      catch(ClassNotFoundException e)
+      {
+         return;
+      }
+      com.kingsrook.qbits.email.webhook.EmailWebhookRouteProvider.register(instance);
+   }
 }

src/main/java/com/kingsrook/qbits/email/api/EmailApi.java

@@ -0,0 +1,592 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Function;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTableCustomizers;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.outbox.EmailEffects;
+import com.kingsrook.qbits.email.outbox.EmailService;
+import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
+import com.kingsrook.qbits.email.support.EmailApiMapper;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qbits.email.template.CrmLegacyTemplateRenderer;
+import com.kingsrook.qbits.email.template.EmailTemplateRenderer;
+import com.kingsrook.qbits.email.template.EmailTemplates;
+import com.kingsrook.qbits.email.template.VariableSchema;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** Stable contract for other qbits. Changes within a 0.x minor release line are
+ ** additive only; implementation packages are not API and may change.
+ ** Database operations use the current QContext. Reads run as the email system
+ ** and return only the documented projection; callers must authorize any
+ ** exposure of this metadata to their own users. Sends retain all existing
+ ** permission, validation, PHI, suppression and recipient checks.
+ *******************************************************************************/
+public final class EmailApi
+{
+   private static final Set<String> MESSAGE_FIELDS = Set.of("id", "status", "category", "idempotencyKey", "rfcMessageId", "providerMessageId",
+      "templateId", "linkedTableName", "linkedRecordId", "createDate", "sentDate", "deliveredDate");
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailApi()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** True only when the email qbit was produced in the supplied instance.
+    ** Does not require a current context; null is not installed.
+    *******************************************************************************/
+   public static boolean isInstalled(QInstance instance)
+   {
+      return (EmailRuntime.config(instance) != null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Queue a message. QUEUED is not a delivery acknowledgement. Null requests
+    ** are refused by the same service used by core messaging.
+    *******************************************************************************/
+   public static EmailApiResult send(EmailApiRequest request) throws QException
+   {
+      return (EmailApiMapper.result(EmailService.send(EmailApiMapper.request(request))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Commit one durable handoff with the effect key as the idempotency key.
+    ** Refuse null requests, blank or over-500-character keys, conflicting keys
+    ** and caller transactions before changing the request. Suppression is REFUSED,
+    ** including replays; a retained audit row is returned. Success acknowledges
+    ** committed storage, not delivery. Database failures propagate as QException.
+    *******************************************************************************/
+   public static EmailApiEffectResult sendOnce(EmailApiRequest request, String effectKey) throws QException
+   {
+      if(request == null || effectKey == null || effectKey.isBlank() || effectKey.length() > 500
+         || request.getTransaction() != null
+         || request.getIdempotencyKey() != null && !request.getIdempotencyKey().equals(effectKey))
+      {
+         return (new EmailApiEffectResult(EmailApiEffectOutcome.REFUSED, null));
+      }
+      request.withIdempotencyKey(effectKey);
+      var result = EmailEffects.send(EmailApiMapper.request(request), effectKey);
+      EmailApiMessage message = result.message() == null ? null : getMessage(result.message().id())
+         .orElseThrow(() -> new QException("Queued email reference is unavailable"));
+      return (new EmailApiEffectResult(EmailApiEffectOutcome.valueOf(result.outcome().name()), message));
+   }
+
+
+
+   /*******************************************************************************
+    ** Checked single-recipient template handoff for CRM history. Content is returned
+    ** only after the stored envelope matches the caller-authorized template/version.
+    ** Existing metadata-only APIs deliberately remain unchanged.
+    *******************************************************************************/
+   public static EmailApiTemplateEffectResult sendTemplateOnce(Integer templateId, EmailApiRequest request, String effectKey) throws QException
+   {
+      if(request == null || request.getTo().size() != 1 || !request.getCc().isEmpty() || !request.getBcc().isEmpty()
+         || request.getSenderQbit() == null || request.getSenderProcess() == null
+         || request.getLinkedTableName() == null || request.getLinkedRecordId() == null)
+      {
+         throw (new IllegalArgumentException("Checked template delivery requires one recipient, sender and linked record"));
+      }
+      List<String> recipients;
+      try
+      {
+         recipients = EmailService.addresses(request.getTo());
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Checked template delivery requires a valid recipient", e));
+      }
+      if(recipients.size() != 1)
+      {
+         throw (new IllegalArgumentException("Checked template delivery requires exactly one mailbox"));
+      }
+      request.withTo(recipients);
+      EmailApiRenderedTemplate selected = renderTemplate(templateId, request);
+      request.withTemplateName(selected.templateName());
+      EmailApiEffectResult effect = sendOnce(request, effectKey);
+      if(effect.outcome() == EmailApiEffectOutcome.REFUSED || effect.message() == null)
+      {
+         return (new EmailApiTemplateEffectResult(effect, null));
+      }
+      List<QRecord> rows = read(EmailTables.MESSAGE, EmailStore.equal("id", effect.message().id()).withLimit(1),
+         Set.of("templateId", "templateVersionId", "senderQbit", "senderProcess", "linkedTableName", "linkedRecordId", "category",
+            "toAddresses", "ccAddresses", "bccAddresses", "suppressedAddresses", "subject"));
+      if(rows.isEmpty())
+      {
+         throw (new QException("Checked template delivery is unavailable"));
+      }
+      QRecord row = rows.getFirst();
+      if(!java.util.Objects.equals(selected.templateId(), row.getValueInteger("templateId"))
+         || !java.util.Objects.equals(selected.versionId(), row.getValueInteger("templateVersionId"))
+         || !java.util.Objects.equals(request.getSenderQbit(), row.getValueString("senderQbit"))
+         || !java.util.Objects.equals(request.getSenderProcess(), row.getValueString("senderProcess"))
+         || !java.util.Objects.equals(request.getLinkedTableName(), row.getValueString("linkedTableName"))
+         || !java.util.Objects.equals(request.getLinkedRecordId(), row.getValueString("linkedRecordId"))
+         || !java.util.Objects.equals(request.getCategory().name(), row.getValueString("category"))
+         || !java.util.Objects.equals(request.getTo().getFirst(), row.getValueString("toAddresses"))
+         || !blank(row.getValueString("ccAddresses")) || !blank(row.getValueString("bccAddresses")) || !blank(row.getValueString("suppressedAddresses")))
+      {
+         throw (new QException("Checked template delivery envelope does not match"));
+      }
+      return (new EmailApiTemplateEffectResult(effect, row.getValueString("subject")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Optional empty recipient columns are equivalent.
+    *******************************************************************************/
+   private static boolean blank(String value)
+   {
+      return (value == null || value.isBlank());
+   }
+
+
+
+   /*******************************************************************************
+    ** Render as the caller: template and version reads enforce table/record locks.
+    ** Native kinds retain their category and classification policy. No PHI export.
+    *******************************************************************************/
+   public static EmailApiRenderedTemplate renderTemplate(Integer templateId, EmailApiRequest request) throws QException
+   {
+      if(templateId == null || request == null || request.getCategory() == null)
+      {
+         throw (new IllegalArgumentException("Template and expected delivery category are required"));
+      }
+      QRecord template = visibleTemplateRecord(EmailTables.TEMPLATE, EmailStore.equal("id", templateId));
+      if(Boolean.TRUE.equals(template.getValueBoolean("phiApproved")))
+      {
+         throw (new IllegalArgumentException("PHI-approved templates require the protected template send path"));
+      }
+      QRecord version = visibleActiveVersion(templateId, request.getLocale());
+      QRecord rendered;
+      if("CRM_LEGACY".equals(template.getValueString("kind")))
+      {
+         if(request.getCategory() != EmailApiCategory.TRANSACTIONAL && request.getCategory() != EmailApiCategory.MARKETING)
+         {
+            throw (new IllegalArgumentException("Legacy CRM templates support only transactional or marketing delivery"));
+         }
+         rendered = CrmLegacyTemplateRenderer.render(template, version, request.getVariables(), request.getSubject(), request.getMarkdownBody());
+      }
+      else
+      {
+         if(!Set.of("MARKDOWN", "HTML", "MJML").contains(template.getValueString("kind")))
+         {
+            throw (new IllegalArgumentException("Unsupported template kind"));
+         }
+         if(request.getSubject() != null || request.getMarkdownBody() != null || request.getHtmlBody() != null || request.getTextBody() != null)
+         {
+            throw (new IllegalArgumentException("Native template content cannot be overridden"));
+         }
+         var renderer = new EmailTemplateRenderer(template, version, EmailApiMapper.request(request));
+         rendered = renderer.renderContent("render", "");
+      }
+      return (new EmailApiRenderedTemplate(templateId, version.getValueInteger("id"), template.getValueString("name"), template.getValueString("kind"), rendered.getValueString("subject"),
+         rendered.getValueString("markdownBody"), rendered.getValueString("htmlBody"), rendered.getValueString("textBody")));
+   }
+
+   /*******************************************************************************
+    ** Declare inputs without exposing content; CRM only computes values in use.
+    *******************************************************************************/
+   public static Set<String> templateVariableNames(Integer templateId) throws QException
+   {
+      QRecord template = visibleTemplateRecord(EmailTables.TEMPLATE, EmailStore.equal("id", templateId));
+      QRecord version = visibleActiveVersion(templateId, "en");
+      if("CRM_LEGACY".equals(template.getValueString("kind")))
+      {
+         String source = String.valueOf(version.getValue("subject")) + version.getValue("bodySource") + version.getValue("textSource");
+         return (Set.of("contact.firstName", "contact.lastName", "company.name", "owner.name", "unsubscribeUrl").stream()
+            .filter(name -> source.contains("{{" + name + "}}")).collect(java.util.stream.Collectors.toUnmodifiableSet()));
+      }
+      return (new VariableSchema(version.getValueString("variablesSchema")).entries().keySet());
+   }
+
+   /*******************************************************************************
+    ** Read only versions visible to the caller, preferring locale then English.
+    *******************************************************************************/
+   private static QRecord visibleActiveVersion(Integer templateId, String requestedLocale) throws QException
+   {
+      String locale = requestedLocale == null ? "en" : requestedLocale;
+      QueryInput versionQuery = new QueryInput(EmailTables.VERSION).withShouldFetchHeavyFields(true)
+         .withFilter(EmailStore.equal("templateId", templateId).withCriteria(new QFilterCriteria("status", QCriteriaOperator.EQUALS, "ACTIVE")));
+      new EmailPermissionChecker().checkPermissionsThrowing(versionQuery, QContext.getQInstance().getTable(EmailTables.VERSION));
+      List<QRecord> versions = new QueryAction().execute(versionQuery).getRecords();
+      QRecord version = versions.stream().filter(row -> locale.equals(row.getValueString("locale"))).findFirst()
+         .orElseGet(() -> versions.stream().filter(row -> "en".equals(row.getValueString("locale"))).findFirst().orElse(null));
+      if(version == null)
+      {
+         throw (new IllegalArgumentException("Template has no visible active version"));
+      }
+      return (version);
+   }
+
+   /*******************************************************************************
+    ** Ordinary query actions deliberately avoid the email system-write scope.
+    *******************************************************************************/
+   private static QRecord visibleTemplateRecord(String table, QQueryFilter filter) throws QException
+   {
+      QueryInput query = new QueryInput(table).withShouldFetchHeavyFields(true).withFilter(filter);
+      new EmailPermissionChecker().checkPermissionsThrowing(query, QContext.getQInstance().getTable(table));
+      List<QRecord> rows = new QueryAction().execute(query).getRecords();
+      if(rows.size() != 1)
+      {
+         throw (new IllegalArgumentException("Template is unavailable"));
+      }
+      return (rows.getFirst());
+   }
+
+   /*******************************************************************************
+    ** Create a validated template and active version once. Returns false when
+    ** it already exists. Invalid definitions throw IllegalArgumentException.
+    ** Does not grant PHI approval or overwrite administrator edits.
+    *******************************************************************************/
+   public static boolean ensureTemplate(EmailApiTemplate template) throws QException
+   {
+      return (EmailTemplates.ensure(EmailApiMapper.template(template)));
+   }
+
+
+
+   /*******************************************************************************
+    ** System lookup of delivery metadata. Null and unknown ids return empty.
+    *******************************************************************************/
+   public static Optional<EmailApiMessage> getMessage(Integer messageId) throws QException
+   {
+      if(messageId == null)
+      {
+         return (Optional.empty());
+      }
+      List<QRecord> rows = read(EmailTables.MESSAGE, EmailStore.equal("id", messageId).withLimit(1), MESSAGE_FIELDS);
+      return (rows.isEmpty() ? Optional.empty() : Optional.of(message(rows.getFirst())));
+   }
+
+
+
+   /*******************************************************************************
+    ** System lookup by exact effect or application key. Null, blank and unknown
+    ** keys return empty. Returns current metadata without message content.
+    *******************************************************************************/
+   public static Optional<EmailApiMessage> getMessageByIdempotencyKey(String key) throws QException
+   {
+      return (findMessage("idempotencyKey", key));
+   }
+
+
+
+   /*******************************************************************************
+    ** System lookup by the exact bracketed RFC Message-ID stored at enqueue time.
+    ** Null, blank and unknown ids return empty; provider response ids are distinct.
+    *******************************************************************************/
+   public static Optional<EmailApiMessage> getMessageByRfcMessageId(String rfcMessageId) throws QException
+   {
+      return (findMessage("rfcMessageId", rfcMessageId));
+   }
+
+
+
+   /*******************************************************************************
+    ** Share exact-key lookup semantics and the metadata-only projection.
+    *******************************************************************************/
+   private static Optional<EmailApiMessage> findMessage(String field, String value) throws QException
+   {
+      if(value == null || value.isBlank())
+      {
+         return (Optional.empty());
+      }
+      List<QRecord> rows = read(EmailTables.MESSAGE, EmailStore.equal(field, value).withLimit(1), MESSAGE_FIELDS);
+      return (rows.isEmpty() ? Optional.empty() : Optional.of(message(rows.getFirst())));
+   }
+
+
+
+   /*******************************************************************************
+    ** System lookup by literal prefix, ordered by ascending message id. Prefix
+    ** must be nonblank and limit positive; invalid arguments are rejected.
+    ** Returns at most limit rows, without message content or recipient data.
+    *******************************************************************************/
+   public static List<EmailApiMessage> findMessagesByIdempotencyKeyPrefix(String prefix, int limit) throws QException
+   {
+      if(prefix == null || prefix.isBlank() || limit < 1)
+      {
+         throw (new IllegalArgumentException("A nonblank idempotency key prefix and a positive limit are required"));
+      }
+      ///////////////////////////////////////////////////////////////////////////
+      // QQQ SQL STARTS_WITH uses LIKE without escaping. Narrow by the literal  //
+      // portion before any wildcard, then check the full prefix in Java. Page //
+      // by id so wildcard false positives cannot consume the requested limit. //
+      ///////////////////////////////////////////////////////////////////////////
+      String candidatePrefix = prefix.split("[%_\\\\]", 2)[0];
+      List<EmailApiMessage> messages = new ArrayList<>();
+      int lastId = 0;
+      while(messages.size() < limit)
+      {
+         int batchSize = Math.min(500, limit - messages.size());
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("idempotencyKey", QCriteriaOperator.STARTS_WITH, candidatePrefix))
+            .withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId))
+            .withOrderBy(new QFilterOrderBy("id")).withLimit(batchSize);
+         List<QRecord> rows = read(EmailTables.MESSAGE, filter, MESSAGE_FIELDS);
+         for(QRecord row : rows)
+         {
+            lastId = row.getValueInteger("id");
+            if(row.getValueString("idempotencyKey") != null && row.getValueString("idempotencyKey").startsWith(prefix))
+            {
+               messages.add(message(row));
+            }
+         }
+         if(rows.size() < batchSize)
+         {
+            break;
+         }
+      }
+      return (List.copyOf(messages));
+   }
+
+
+
+   /*******************************************************************************
+    ** Enabled sender rows of an enabled named provider, ordered by id. Null
+    ** selects the effective default provider. No match returns an empty list.
+    ** The provider's legacy from-address fallback is not a sender row.
+    *******************************************************************************/
+   public static List<EmailApiSenderAddress> listSenderAddresses(String providerName) throws QException
+   {
+      QRecord provider = provider(QContext.getQInstance(), providerName);
+      if(provider == null)
+      {
+         return (List.of());
+      }
+      QQueryFilter filter = EmailStore.equal("providerId", provider.getValueInteger("id"))
+         .withCriteria(new QFilterCriteria("enabled", QCriteriaOperator.EQUALS, true)).withOrderBy(new QFilterOrderBy("id"));
+      return (read(EmailTables.SENDER, filter, Set.of("id", "address", "displayName", "isDefault"))
+         .stream().map(row -> new EmailApiSenderAddress(row.getValueInteger("id"), row.getValueString("address"),
+            row.getValueString("displayName"), Boolean.TRUE.equals(row.getValueBoolean("isDefault")))).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** Effective enabled default: the configured name takes precedence over the
+    ** default row. Empty when absent, disabled or ambiguous. An installed
+    ** instance must be the current QContext instance, otherwise this throws.
+    *******************************************************************************/
+   public static Optional<String> defaultProviderName(QInstance instance) throws QException
+   {
+      QRecord provider = provider(instance, null);
+      return (provider == null ? Optional.empty() : Optional.of(provider.getValueString("name")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Preflight the default sending configuration for a category. Null category
+    ** means TRANSACTIONAL. This does not validate a particular template,
+    ** recipient or permission, or contact a transport. PHI callers use the
+    ** overload with phiApproved set to true.
+    *******************************************************************************/
+   public static EmailApiReadiness readiness(QInstance instance, EmailApiCategory category) throws QException
+   {
+      return (readiness(instance, category, false));
+   }
+
+
+
+   /*******************************************************************************
+    ** Also check prerequisites for a PHI-approved template. PHI is a template
+    ** property, not an email category. Checks body key availability and provider
+    ** PHI/tracking policy; does not approve a template. Resolver failures are
+    ** reported as missing keys without exposing exception details or values.
+    *******************************************************************************/
+   public static EmailApiReadiness readiness(QInstance instance, EmailApiCategory category, boolean phiApproved) throws QException
+   {
+      List<String> reasons = new ArrayList<>();
+      Set<EmailApiReadinessCheck> failed = EnumSet.noneOf(EmailApiReadinessCheck.class);
+      var config = EmailRuntime.config(instance);
+      if(config == null)
+      {
+         return (new EmailApiReadiness(false, List.of("Email qbit is not installed"), Set.of(EmailApiReadinessCheck.NOT_INSTALLED)));
+      }
+      QRecord provider = provider(instance, null);
+      if(provider == null)
+      {
+         reasons.add("An enabled named or default provider is required");
+         failed.add(EmailApiReadinessCheck.PROVIDER_MISSING);
+      }
+      else
+      {
+         if(!EmailTableCustomizers.validateProvider(provider, config).isEmpty())
+         {
+            reasons.add("The default provider configuration is invalid");
+            failed.add(EmailApiReadinessCheck.PROVIDER_INVALID);
+         }
+         if(phiApproved)
+         {
+            try
+            {
+               EmailTemplateRenderer.checkProvider(provider);
+            }
+            catch(IllegalArgumentException e)
+            {
+               reasons.add("PHI email needs a PHI-enabled provider with open and click tracking disabled");
+               failed.add(EmailApiReadinessCheck.PHI_PROVIDER);
+            }
+         }
+      }
+      if(category == EmailApiCategory.MARKETING)
+      {
+         try
+         {
+            if(config.getPublicBaseUrl() == null || config.getPublicBaseUrl().isBlank())
+            {
+               throw (new IllegalArgumentException());
+            }
+            VariableSchema.url(config.getPublicBaseUrl());
+         }
+         catch(IllegalArgumentException e)
+         {
+            reasons.add("MARKETING email needs a valid publicBaseUrl");
+            failed.add(EmailApiReadinessCheck.PUBLIC_BASE_URL);
+         }
+         if(!hasSecret(config.getSecretResolver(), "QQQ_EMAIL_UNSUBSCRIBE_KEY"))
+         {
+            reasons.add("MARKETING email needs QQQ_EMAIL_UNSUBSCRIBE_KEY");
+            failed.add(EmailApiReadinessCheck.UNSUBSCRIBE_KEY);
+         }
+         List<QRecord> brands = read(EmailTables.BRAND, EmailStore.equal("isDefault", true).withLimit(2), Set.of("id", "postalAddress"));
+         if(brands.size() != 1 || brands.getFirst().getValueString("postalAddress") == null || brands.getFirst().getValueString("postalAddress").isBlank())
+         {
+            reasons.add("MARKETING email needs a default brand with a postal address");
+            failed.add(EmailApiReadinessCheck.BRAND_POSTAL_ADDRESS);
+         }
+      }
+      if(phiApproved && !hasSecret(config.getSecretResolver(), "QQQ_EMAIL_BODY_KEY"))
+      {
+         reasons.add("PHI email needs QQQ_EMAIL_BODY_KEY");
+         failed.add(EmailApiReadinessCheck.BODY_KEY);
+      }
+      return (new EmailApiReadiness(reasons.isEmpty(), reasons, failed));
+   }
+
+
+
+   /*******************************************************************************
+    ** Presence only; neither retain values nor expose resolver failures.
+    *******************************************************************************/
+   private static boolean hasSecret(Function<String, String> resolver, String name)
+   {
+      try
+      {
+         String value = resolver.apply(name);
+         return (value != null && !value.isBlank());
+      }
+      catch(RuntimeException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Match the enqueue service's configured-name/default-row precedence.
+    ** Refuse a mismatched context instead of reading another instance's data.
+    *******************************************************************************/
+   private static QRecord provider(QInstance instance, String name) throws QException
+   {
+      var config = EmailRuntime.config(instance);
+      if(config == null)
+      {
+         return (null);
+      }
+      if(instance != QContext.getQInstance())
+      {
+         throw (new IllegalArgumentException("The supplied instance must be the current QContext instance"));
+      }
+      String effectiveName = name == null ? config.getDefaultProviderName() : name;
+      QQueryFilter filter = EmailStore.equal("enabled", true)
+         .withCriteria(new QFilterCriteria(effectiveName == null ? "isDefault" : "name", QCriteriaOperator.EQUALS, effectiveName == null ? true : effectiveName))
+         .withLimit(2);
+      List<QRecord> providers = SystemWrites.query(EmailTables.PROVIDER, filter);
+      return (providers.size() == 1 ? providers.getFirst() : null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Read an explicit projection; message bodies are never fetched here.
+    *******************************************************************************/
+   private static List<QRecord> read(String table, QQueryFilter filter, Set<String> fields) throws QException
+   {
+      return (SystemWrites.call(() -> new QueryAction().execute(new QueryInput(table).withFilter(filter)
+         .withFieldNamesToInclude(fields).withShouldFetchHeavyFields(false).withShouldOmitHiddenFields(false)).getRecords()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve the template name and copy only the approved metadata fields.
+    *******************************************************************************/
+   private static EmailApiMessage message(QRecord row) throws QException
+   {
+      String templateName = null;
+      if(row.getValueInteger("templateId") != null)
+      {
+         List<QRecord> templates = read(EmailTables.TEMPLATE, EmailStore.equal("id", row.getValueInteger("templateId")).withLimit(1), Set.of("id", "name"));
+         if(!templates.isEmpty())
+         {
+            templateName = templates.getFirst().getValueString("name");
+         }
+      }
+      String category = row.getValueString("category");
+      return (new EmailApiMessage(row.getValueInteger("id"), row.getValueString("status"), category == null ? null : EmailApiCategory.valueOf(category),
+         row.getValueString("idempotencyKey"), row.getValueString("rfcMessageId"), row.getValueString("providerMessageId"), templateName, row.getValueString("linkedTableName"),
+         row.getValueString("linkedRecordId"), row.getValueInstant("createDate"), row.getValueInstant("sentDate"), row.getValueInstant("deliveredDate")));
+   }
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiCategory.java

@@ -0,0 +1,33 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Stable sending categories; PHI approval belongs to the template, not the category.
+ *******************************************************************************/
+public enum EmailApiCategory
+{
+   TRANSACTIONAL,
+   NOTIFICATION,
+   MARKETING,
+   SECURITY
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiEffectOutcome.java

@@ -0,0 +1,31 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Durable handoff outcomes. Operational failures propagate to the caller.
+ *******************************************************************************/
+public enum EmailApiEffectOutcome
+{
+   QUEUED_OR_DUPLICATE,
+   REFUSED
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiEffectResult.java

@@ -0,0 +1,30 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Durable handoff result. The message is null when no outbox row was retained.
+ ** Suppressed audit rows carry metadata even though the outcome is REFUSED.
+ *******************************************************************************/
+public record EmailApiEffectResult(EmailApiEffectOutcome outcome, EmailApiMessage message)
+{
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiMessage.java

@@ -0,0 +1,34 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.time.Instant;
+
+
+/*******************************************************************************
+ ** Immutable delivery metadata. No addresses, subject, bodies or variable snapshots.
+ ** Status is the persisted delivery state, distinct from EmailApiStatus enqueue outcomes.
+ *******************************************************************************/
+public record EmailApiMessage(Integer id, String status, EmailApiCategory category, String idempotencyKey, String rfcMessageId, String providerMessageId,
+   String templateName, String linkedTableName, String linkedRecordId, Instant createDate, Instant sentDate, Instant deliveredDate)
+{
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiReadiness.java

@@ -0,0 +1,52 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+
+
+/*******************************************************************************
+ ** Configuration preflight, not a delivery guarantee. Reasons never contain secret values.
+ *******************************************************************************/
+public record EmailApiReadiness(boolean ready, List<String> reasons, Set<EmailApiReadinessCheck> failedChecks)
+{
+   /*******************************************************************************
+    ** Copy configuration reasons.
+    *******************************************************************************/
+   public EmailApiReadiness
+   {
+      reasons = List.copyOf(reasons);
+      failedChecks = failedChecks == null || failedChecks.isEmpty() ? Set.of() : Set.copyOf(EnumSet.copyOf(failedChecks));
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether a specific prerequisite failed.
+    *******************************************************************************/
+   public boolean failed(EmailApiReadinessCheck check)
+   {
+      return (failedChecks.contains(check));
+   }
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiReadinessCheck.java

@@ -0,0 +1,38 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** One readiness prerequisite, so callers can react to specific gaps without
+ ** parsing reason text.
+ *******************************************************************************/
+public enum EmailApiReadinessCheck
+{
+   NOT_INSTALLED,
+   PROVIDER_MISSING,
+   PROVIDER_INVALID,
+   PHI_PROVIDER,
+   PUBLIC_BASE_URL,
+   UNSUBSCRIBE_KEY,
+   BRAND_POSTAL_ADDRESS,
+   BODY_KEY
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiRenderedTemplate.java

@@ -0,0 +1,30 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Typed content and provenance. HTML must never be reinterpreted as Markdown.
+ *******************************************************************************/
+public record EmailApiRenderedTemplate(Integer templateId, Integer versionId, String templateName, String kind, String subject,
+                                       String markdownBody, String htmlBody, String textBody)
+{
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiRequest.java

@@ -0,0 +1,670 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+
+
+/*******************************************************************************
+ ** Stable enqueue request. One send always goes through the outbox.
+ ** Null category means TRANSACTIONAL for ad-hoc mail; templates select their category.
+ ** Recipient lists and variable maps are mutable request-building state.
+ *******************************************************************************/
+public final class EmailApiRequest
+{
+   private List<String> to = new ArrayList<>();
+   private List<String> cc = new ArrayList<>();
+   private List<String> bcc = new ArrayList<>();
+   private String from;
+   private Integer fromAddressId;
+   private String replyTo;
+   private String subject;
+   private String markdownBody;
+   private String htmlBody;
+   private String textBody;
+   private String providerName;
+   private String templateName;
+   private String brandName;
+   private String locale = "en";
+   private EmailApiCategory category;
+   private String idempotencyKey;
+   private QBackendTransaction transaction;
+   private String transactionBackendName;
+   private Instant sendAfter;
+   private String linkedTableName;
+   private String linkedRecordId;
+   private String senderQbit;
+   private String senderProcess;
+   private Map<String, Serializable> variables = new LinkedHashMap<>();
+   private Map<String, RecordVariable> recordVariables = new LinkedHashMap<>();
+
+
+
+   /*******************************************************************************
+    ** Getter for to.
+    *******************************************************************************/
+   public List<String> getTo()
+   {
+      return (to);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for to.
+    *******************************************************************************/
+   public EmailApiRequest withTo(List<String> to)
+   {
+      this.to = to;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for cc.
+    *******************************************************************************/
+   public List<String> getCc()
+   {
+      return (cc);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for cc.
+    *******************************************************************************/
+   public EmailApiRequest withCc(List<String> cc)
+   {
+      this.cc = cc;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bcc.
+    *******************************************************************************/
+   public List<String> getBcc()
+   {
+      return (bcc);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for bcc.
+    *******************************************************************************/
+   public EmailApiRequest withBcc(List<String> bcc)
+   {
+      this.bcc = bcc;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for from.
+    *******************************************************************************/
+   public String getFrom()
+   {
+      return (from);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for from.
+    *******************************************************************************/
+   public EmailApiRequest withFrom(String from)
+   {
+      this.from = from;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fromAddressId.
+    *******************************************************************************/
+   public Integer getFromAddressId()
+   {
+      return (fromAddressId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fromAddressId.
+    *******************************************************************************/
+   public EmailApiRequest withFromAddressId(Integer fromAddressId)
+   {
+      this.fromAddressId = fromAddressId;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for replyTo.
+    *******************************************************************************/
+   public String getReplyTo()
+   {
+      return (replyTo);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for replyTo.
+    *******************************************************************************/
+   public EmailApiRequest withReplyTo(String replyTo)
+   {
+      this.replyTo = replyTo;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for subject.
+    *******************************************************************************/
+   public String getSubject()
+   {
+      return (subject);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for subject.
+    *******************************************************************************/
+   public EmailApiRequest withSubject(String subject)
+   {
+      this.subject = subject;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for markdownBody.
+    *******************************************************************************/
+   public String getMarkdownBody()
+   {
+      return (markdownBody);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for markdownBody.
+    *******************************************************************************/
+   public EmailApiRequest withMarkdownBody(String markdownBody)
+   {
+      this.markdownBody = markdownBody;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for htmlBody.
+    *******************************************************************************/
+   public String getHtmlBody()
+   {
+      return (htmlBody);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for htmlBody.
+    *******************************************************************************/
+   public EmailApiRequest withHtmlBody(String htmlBody)
+   {
+      this.htmlBody = htmlBody;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for textBody.
+    *******************************************************************************/
+   public String getTextBody()
+   {
+      return (textBody);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for textBody.
+    *******************************************************************************/
+   public EmailApiRequest withTextBody(String textBody)
+   {
+      this.textBody = textBody;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for providerName.
+    *******************************************************************************/
+   public String getProviderName()
+   {
+      return (providerName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for providerName.
+    *******************************************************************************/
+   public EmailApiRequest withProviderName(String providerName)
+   {
+      this.providerName = providerName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for templateName.
+    *******************************************************************************/
+   public String getTemplateName()
+   {
+      return (templateName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for templateName.
+    *******************************************************************************/
+   public EmailApiRequest withTemplateName(String templateName)
+   {
+      this.templateName = templateName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for brandName.
+    *******************************************************************************/
+   public String getBrandName()
+   {
+      return (brandName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for brandName.
+    *******************************************************************************/
+   public EmailApiRequest withBrandName(String brandName)
+   {
+      this.brandName = brandName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for locale.
+    *******************************************************************************/
+   public String getLocale()
+   {
+      return (locale);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for locale.
+    *******************************************************************************/
+   public EmailApiRequest withLocale(String locale)
+   {
+      this.locale = locale;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for category.
+    *******************************************************************************/
+   public EmailApiCategory getCategory()
+   {
+      return (category);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for category.
+    *******************************************************************************/
+   public EmailApiRequest withCategory(EmailApiCategory category)
+   {
+      this.category = category;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for idempotencyKey.
+    *******************************************************************************/
+   public String getIdempotencyKey()
+   {
+      return (idempotencyKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for idempotencyKey.
+    *******************************************************************************/
+   public EmailApiRequest withIdempotencyKey(String idempotencyKey)
+   {
+      this.idempotencyKey = idempotencyKey;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for the optional caller transaction. sendOnce refuses this option.
+    *******************************************************************************/
+   public QBackendTransaction getTransaction()
+   {
+      return (transaction);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for the declared backend of the caller transaction.
+    *******************************************************************************/
+   public String getTransactionBackendName()
+   {
+      return (transactionBackendName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Join a caller transaction for ordinary send; another backend defers enqueue
+    ** until commit. Declare its backend because QBackendTransaction does not expose
+    ** it. sendOnce refuses any caller transaction to guarantee committed handoff.
+    *******************************************************************************/
+   public EmailApiRequest withTransaction(QBackendTransaction transaction, String backendName)
+   {
+      this.transaction = transaction;
+      this.transactionBackendName = backendName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sendAfter.
+    *******************************************************************************/
+   public Instant getSendAfter()
+   {
+      return (sendAfter);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for sendAfter.
+    *******************************************************************************/
+   public EmailApiRequest withSendAfter(Instant sendAfter)
+   {
+      this.sendAfter = sendAfter;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for linkedTableName.
+    *******************************************************************************/
+   public String getLinkedTableName()
+   {
+      return (linkedTableName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for linkedTableName.
+    *******************************************************************************/
+   public EmailApiRequest withLinkedTableName(String linkedTableName)
+   {
+      this.linkedTableName = linkedTableName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for linkedRecordId.
+    *******************************************************************************/
+   public String getLinkedRecordId()
+   {
+      return (linkedRecordId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for linkedRecordId.
+    *******************************************************************************/
+   public EmailApiRequest withLinkedRecordId(String linkedRecordId)
+   {
+      this.linkedRecordId = linkedRecordId;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for senderQbit.
+    *******************************************************************************/
+   public String getSenderQbit()
+   {
+      return (senderQbit);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for senderQbit.
+    *******************************************************************************/
+   public EmailApiRequest withSenderQbit(String senderQbit)
+   {
+      this.senderQbit = senderQbit;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for senderProcess.
+    *******************************************************************************/
+   public String getSenderProcess()
+   {
+      return (senderProcess);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for senderProcess.
+    *******************************************************************************/
+   public EmailApiRequest withSenderProcess(String senderProcess)
+   {
+      this.senderProcess = senderProcess;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for variables.
+    *******************************************************************************/
+   public Map<String, Serializable> getVariables()
+   {
+      return (variables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for variables.
+    *******************************************************************************/
+   public EmailApiRequest withVariables(Map<String, Serializable> variables)
+   {
+      this.variables = variables;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for recordVariables.
+    *******************************************************************************/
+   public Map<String, RecordVariable> getRecordVariables()
+   {
+      return (recordVariables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for recordVariables.
+    *******************************************************************************/
+   public EmailApiRequest withRecordVariables(Map<String, RecordVariable> recordVariables)
+   {
+      this.recordVariables = recordVariables;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Append to recipients. Sending still enforces category and PHI recipient rules.
+    *******************************************************************************/
+   public EmailApiRequest withTo(String... addresses)
+   {
+      to.addAll(List.of(addresses));
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Append cc recipients. Sending still enforces category and PHI recipient rules.
+    *******************************************************************************/
+   public EmailApiRequest withCc(String... addresses)
+   {
+      cc.addAll(List.of(addresses));
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Append bcc recipients. Sending still enforces category and PHI recipient rules.
+    *******************************************************************************/
+   public EmailApiRequest withBcc(String... addresses)
+   {
+      bcc.addAll(List.of(addresses));
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Link the message to an application record.
+    *******************************************************************************/
+   public EmailApiRequest withLinkedRecord(String table, Object id)
+   {
+      linkedTableName = table;
+      linkedRecordId = id == null ? null : String.valueOf(id);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Identify the producing qbit and process.
+    *******************************************************************************/
+   public EmailApiRequest withSender(String qbit, String process)
+   {
+      senderQbit = qbit;
+      senderProcess = process;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind one variable; template schema and classification checks still apply.
+    *******************************************************************************/
+   public EmailApiRequest withVariable(String name, Serializable value)
+   {
+      variables.put(name, value);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind record provenance without reading or snapshotting the record.
+    *******************************************************************************/
+   public EmailApiRequest withRecordVariable(String name, String table, Serializable pk)
+   {
+      recordVariables.put(name, new RecordVariable(table, pk));
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** A record reference; values are resolved and classified by the sending service.
+    *******************************************************************************/
+   public record RecordVariable(String table, Serializable id)
+   {
+   }
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiResult.java

@@ -0,0 +1,39 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.util.List;
+
+
+/*******************************************************************************
+ ** Immutable enqueue result with plain refusal reasons.
+ *******************************************************************************/
+public record EmailApiResult(Integer messageId, EmailApiStatus status, List<String> reasons)
+{
+   /*******************************************************************************
+    ** Copy reasons so callers cannot mutate an outcome.
+    *******************************************************************************/
+   public EmailApiResult
+   {
+      reasons = List.copyOf(reasons);
+   }
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiSenderAddress.java

@@ -0,0 +1,29 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** An enabled provider sender address; no provider credentials.
+ *******************************************************************************/
+public record EmailApiSenderAddress(Integer id, String address, String displayName, boolean isDefault)
+{
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiStatus.java

@@ -0,0 +1,33 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Enqueue outcomes. QUEUED acknowledges storage, not delivery.
+ *******************************************************************************/
+public enum EmailApiStatus
+{
+   QUEUED,
+   DUPLICATE,
+   SUPPRESSED,
+   REFUSED
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiTemplate.java

@@ -0,0 +1,319 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+import java.util.ArrayList;
+import java.util.List;
+
+
+/*******************************************************************************
+ ** A create-once template definition. Existing templates and versions are never overwritten.
+ ** New templates are not PHI approved; approval remains a separately authorized operation.
+ *******************************************************************************/
+public final class EmailApiTemplate
+{
+   private String name;
+   private String label;
+   private EmailApiCategory category;
+   private String kind = "MARKDOWN";
+   private String subject;
+   private String body;
+   private String textBody;
+   private String variablesSchema;
+   private List<EmailApiVariable> variables = new ArrayList<>();
+   private String sampleVariables;
+   private String ownerQbit;
+   private String editPermissionName;
+
+
+
+   /*******************************************************************************
+    ** Getter for name.
+    *******************************************************************************/
+   public String getName()
+   {
+      return (name);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for name.
+    *******************************************************************************/
+   public EmailApiTemplate withName(String name)
+   {
+      this.name = name;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for label.
+    *******************************************************************************/
+   public String getLabel()
+   {
+      return (label);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for label.
+    *******************************************************************************/
+   public EmailApiTemplate withLabel(String label)
+   {
+      this.label = label;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for category.
+    *******************************************************************************/
+   public EmailApiCategory getCategory()
+   {
+      return (category);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for category.
+    *******************************************************************************/
+   public EmailApiTemplate withCategory(EmailApiCategory category)
+   {
+      this.category = category;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for kind.
+    *******************************************************************************/
+   public String getKind()
+   {
+      return (kind);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for kind.
+    *******************************************************************************/
+   public EmailApiTemplate withKind(String kind)
+   {
+      this.kind = kind;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for subject.
+    *******************************************************************************/
+   public String getSubject()
+   {
+      return (subject);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for subject.
+    *******************************************************************************/
+   public EmailApiTemplate withSubject(String subject)
+   {
+      this.subject = subject;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for body.
+    *******************************************************************************/
+   public String getBody()
+   {
+      return (body);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for body.
+    *******************************************************************************/
+   public EmailApiTemplate withBody(String body)
+   {
+      this.body = body;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for textBody.
+    *******************************************************************************/
+   public String getTextBody()
+   {
+      return (textBody);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for textBody.
+    *******************************************************************************/
+   public EmailApiTemplate withTextBody(String textBody)
+   {
+      this.textBody = textBody;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for variablesSchema.
+    *******************************************************************************/
+   public String getVariablesSchema()
+   {
+      return (variablesSchema);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for variablesSchema.
+    *******************************************************************************/
+   public EmailApiTemplate withVariablesSchema(String variablesSchema)
+   {
+      this.variablesSchema = variablesSchema;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for variables.
+    *******************************************************************************/
+   public List<EmailApiVariable> getVariables()
+   {
+      return (variables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for variables.
+    *******************************************************************************/
+   public EmailApiTemplate withVariables(List<EmailApiVariable> variables)
+   {
+      this.variables = variables;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sampleVariables.
+    *******************************************************************************/
+   public String getSampleVariables()
+   {
+      return (sampleVariables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for sampleVariables.
+    *******************************************************************************/
+   public EmailApiTemplate withSampleVariables(String sampleVariables)
+   {
+      this.sampleVariables = sampleVariables;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for ownerQbit.
+    *******************************************************************************/
+   public String getOwnerQbit()
+   {
+      return (ownerQbit);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for ownerQbit.
+    *******************************************************************************/
+   public EmailApiTemplate withOwnerQbit(String ownerQbit)
+   {
+      this.ownerQbit = ownerQbit;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for editPermissionName.
+    *******************************************************************************/
+   public String getEditPermissionName()
+   {
+      return (editPermissionName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for editPermissionName.
+    *******************************************************************************/
+   public EmailApiTemplate withEditPermissionName(String editPermissionName)
+   {
+      this.editPermissionName = editPermissionName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Append a typed variable declaration. Use this or variablesSchema, not both.
+    *******************************************************************************/
+   public EmailApiTemplate withVariable(EmailApiVariable variable)
+   {
+      variables.add(variable);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Append a variable declaration using the template schema vocabulary.
+    *******************************************************************************/
+   public EmailApiTemplate withVariable(String name, String label, String type, boolean required, String classification)
+   {
+      return (withVariable(new EmailApiVariable(name, label, type, required, classification)));
+   }
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiTemplateEffectResult.java

@@ -0,0 +1,29 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Exact stored subject for a checked template envelope, never an arbitrary lookup.
+ *******************************************************************************/
+public record EmailApiTemplateEffectResult(EmailApiEffectResult effect, String subject)
+{
+}

src/main/java/com/kingsrook/qbits/email/api/EmailApiVariable.java

@@ -0,0 +1,30 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.api;
+
+
+/*******************************************************************************
+ ** Template variable declaration. Types: STRING, NUMBER, DATE, DATE_TIME, BOOLEAN,
+ ** URL, LIST, RECORD. Classification: PUBLIC, CONFIDENTIAL, PII, PHI or null.
+ *******************************************************************************/
+public record EmailApiVariable(String name, String label, String type, boolean required, String classification)
+{
+}

src/main/java/com/kingsrook/qbits/email/app/EmailApp.java

@@ -24,12 +24,12 @@ package com.kingsrook.qbits.email.app;
 import java.util.List;
 import java.util.Map;
 import com.kingsrook.qbits.email.EmailQBitConfig;
+import com.kingsrook.qbits.email.health.EmailHealthWidget;
 import com.kingsrook.qbits.email.metadata.EmailTables;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
-import com.kingsrook.qqq.backend.core.model.dashboard.widgets.RawHTML;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
@@ -39,7 +39,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 
 
 /*******************************************************************************
- ** Email app with a placeholder overview and the five main tables in navigation.
+ ** Email app with viewer-scoped dashboard widgets and the five main tables in navigation.
  ** Versions and attempts are child lists, and processes are record actions.
  *******************************************************************************/
 public final class EmailApp
@@ -59,14 +59,15 @@ public final class EmailApp
 
 
    /*******************************************************************************
-    ** Placeholder home widget.
+    ** Standard home and record preview widgets.
     *******************************************************************************/
    public static List<QWidgetMetaData> widgets()
    {
       return (List.of(
-         new QWidgetMetaData().withName(HOME_WIDGET).withLabel("Overview").withType(WidgetType.HTML.getType())
-            .withCodeReference(new QCodeReference(HomeRenderer.class)).withGridColumns(12).withIsCard(false)
-            .withPermissionRules(EmailTables.permissionRules())));
+         widget(HOME_WIDGET, "Overview", WidgetType.HTML.getType(), HomeRenderer.class),
+         widget("emailHealth", "Email health", WidgetType.STATISTICS.getType(), EmailHealthWidget.class),
+         widget("emailTemplatePreview", "Preview", WidgetType.HTML.getType(), com.kingsrook.qbits.email.template.EmailPreviewWidget.class)));
+
    }
 
 
@@ -81,7 +82,7 @@ public final class EmailApp
          .withLabel(config.getAppLabel())
          .withIcon(new QIcon("mail"))
          .withPermissionRules(EmailTables.permissionRules())
-         .withWidgets(List.of(HOME_WIDGET));
+         .withWidgets(List.of("emailHealth", HOME_WIDGET));
       for(String name : EmailTables.MAIN)
       {
          if(tables.containsKey(name))
@@ -105,10 +106,18 @@ public final class EmailApp
       @Override
       public RenderWidgetOutput render(RenderWidgetInput input) throws QException
       {
-         return (new RenderWidgetOutput(new RawHTML(null, "<p>Use Messages to follow queued email and Providers to manage delivery.</p>")));
+         return (new RenderWidgetOutput(EmailHome.overview()));
       }
    }
 
 
 
+   /*******************************************************************************
+    ** Full-width widgets follow the Alerts home pattern.
+    *******************************************************************************/
+   private static QWidgetMetaData widget(String name, String label, String type, Class<?> renderer)
+   {
+      return (new QWidgetMetaData().withName(name).withLabel(label).withType(type).withGridColumns(12).withIsCard(false)
+         .withShowReloadButton(true).withCodeReference(new QCodeReference(renderer)).withPermissionRules(EmailTables.permissionRules()));
+   }
 }

src/main/java/com/kingsrook/qbits/email/app/EmailHome.java

@@ -0,0 +1,208 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.app;
+
+
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
+import com.kingsrook.qbits.email.permissions.EmailPermissions;
+import com.kingsrook.qbits.email.template.EmailBuiltIns;
+import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.ChartData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.RawHTML;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Real viewer-scoped data. Counts preserve record security without sampling;
+ ** inline bar charts and rows use the same theme-neutral styles as Webhooks.
+ *******************************************************************************/
+public final class EmailHome
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailHome()
+   {
+   }
+
+   /*******************************************************************************
+    ** Counts and recent messages, without loading bodies or variable snapshots.
+    *******************************************************************************/
+   public static RawHTML overview() throws QException
+   {
+      Instant now = EmailRuntime.clock().instant();
+      List<Integer> totals = new ArrayList<>();
+      String[] fields = {"sentDate", "deliveredDate", "deadLetterDate", "bouncedDate", "complainedDate"};
+      for(int i = 0; i < fields.length; i++)
+      {
+         String eventType = switch(i)
+         {
+            case 1 -> "DELIVERED";
+            case 3 -> "BOUNCED";
+            case 4 -> "COMPLAINED";
+            default -> null;
+         };
+         String field = eventType == null ? fields[i] : "occurredDate";
+         QQueryFilter filter = since(field, now.minus(i < 3 ? 1 : 7, ChronoUnit.DAYS))
+            .withCriteria(field, QCriteriaOperator.LESS_THAN_OR_EQUALS, now);
+         if(eventType != null)
+         {
+            filter.withCriteria("eventType", QCriteriaOperator.EQUALS, eventType);
+         }
+         totals.add(count(eventType == null ? EmailTables.MESSAGE : EmailTables.EVENT, filter));
+      }
+      totals.add(count(EmailTables.SUPPRESSION, new QQueryFilter()));
+      List<QRecord> messages = query(EmailTables.MESSAGE, new QQueryFilter().withOrderBy(new QFilterOrderBy("createDate", false))
+         .withOrderBy(new QFilterOrderBy("id", false)).withLimit(20), List.of("id", "createDate", "toAddresses", "subject", "phiApproved", "status"));
+      boolean admin = EmailPermissionChecker.has(EmailPermissions.ADMIN);
+      List<EmailSetupStatus.Item> setup = List.of();
+      if(admin)
+      {
+         EmailBuiltIns.ensure();
+         setup = EmailSetupStatus.load();
+      }
+      return (new RawHTML(null, EmailHomeView.render(totals, hourly(), messages, suppressions(), setup)));
+   }
+
+   /*******************************************************************************
+    ** Twenty-four UTC hour buckets, counting successful and failed attempts.
+    *******************************************************************************/
+   public static ChartData hourly() throws QException
+   {
+      Instant start = EmailRuntime.clock().instant().truncatedTo(ChronoUnit.HOURS).minus(23, ChronoUnit.HOURS);
+      List<String> labels = new ArrayList<>();
+      List<Number> sent = new ArrayList<>();
+      List<Number> failed = new ArrayList<>();
+      for(int i = 0; i < 24; i++)
+      {
+         Instant hour = start.plus(i, ChronoUnit.HOURS);
+         labels.add(DateTimeFormatter.ofPattern("HH:mm", Locale.ENGLISH).withZone(ZoneOffset.UTC).format(hour));
+         QQueryFilter filter = since("endDate", hour).withCriteria("endDate", QCriteriaOperator.LESS_THAN, hour.plus(1, ChronoUnit.HOURS));
+         sent.add(count(EmailTables.ATTEMPT, filter.clone().withCriteria("outcome", QCriteriaOperator.EQUALS, "SUCCEEDED")));
+         failed.add(count(EmailTables.ATTEMPT, filter.clone().withCriteria("outcome", QCriteriaOperator.IN, List.of("TRANSIENT_FAILURE", "PROVIDER_FAILURE", "PERMANENT_FAILURE", "LEASE_EXPIRED"))));
+      }
+      return (chart(labels, List.of(dataset("Sent", sent, "#16a34a"), dataset("Failed", failed, "#dc2626")), "No completed attempts in the last 24 hours. Counts use UTC hours."));
+   }
+
+   /*******************************************************************************
+    ** Suppression rows created per UTC day and reason, for thirty days.
+    *******************************************************************************/
+   public static ChartData suppressions() throws QException
+   {
+      Instant start = EmailRuntime.clock().instant().truncatedTo(ChronoUnit.DAYS).minus(29, ChronoUnit.DAYS);
+      List<String> labels = new ArrayList<>();
+      List<ChartData.Data.Dataset> datasets = new ArrayList<>();
+      List<String> reasons = List.of("HARD_BOUNCE", "COMPLAINT", "UNSUBSCRIBE", "MANUAL");
+      List<String> colors = List.of("#dc2626", "#d97706", "#2563eb", "#6b7280");
+      for(int r = 0; r < reasons.size(); r++)
+      {
+         List<Number> counts = new ArrayList<>();
+         for(int i = 0; i < 30; i++)
+         {
+            Instant day = start.plus(i, ChronoUnit.DAYS);
+            if(r == 0)
+            {
+               labels.add(DateTimeFormatter.ofPattern("MMM d", Locale.ENGLISH).withZone(ZoneOffset.UTC).format(day));
+            }
+            counts.add(count(EmailTables.SUPPRESSION, since("createdDate", day).withCriteria("createdDate", QCriteriaOperator.LESS_THAN, day.plus(1, ChronoUnit.DAYS))
+               .withCriteria("reason", QCriteriaOperator.EQUALS, reasons.get(r))));
+         }
+         datasets.add(dataset(com.kingsrook.qbits.email.metadata.EmailEnums.SuppressionReason.valueOf(reasons.get(r)).getPossibleValueLabel(), counts, colors.get(r)));
+      }
+      return (chart(labels, datasets, "No new suppressions in the last 30 days. Counts use UTC dates."));
+   }
+
+   /*******************************************************************************
+    ** Standard chart with an honest empty-state sublabel.
+    *******************************************************************************/
+   private static ChartData chart(List<String> labels, List<ChartData.Data.Dataset> datasets, String empty)
+   {
+      ChartData chart = new ChartData().withChartData(new ChartData.Data().withLabels(labels).withDatasets(datasets));
+      boolean any = datasets.stream().anyMatch(d -> d.getData().stream().anyMatch(n -> n.doubleValue() > 0));
+      chart.setSublabel(any ? "Real data visible to your session; UTC buckets." : empty);
+      return (chart);
+   }
+
+   /*******************************************************************************
+    ** A standard chart series.
+    *******************************************************************************/
+   private static ChartData.Data.Dataset dataset(String label, List<Number> values, String color)
+   {
+      return (new ChartData.Data.Dataset().withLabel(label).withData(values).withColor(color));
+   }
+
+   /*******************************************************************************
+    ** Mask display names and all but the first local-part character.
+    *******************************************************************************/
+   public static String mask(String recipients)
+   {
+      try
+      {
+         String address = jakarta.mail.internet.InternetAddress.parse(recipients)[0].getAddress();
+         int at = address.lastIndexOf('@');
+         return (at > 0 ? address.charAt(0) + "***" + address.substring(at) : "[masked]");
+      }
+      catch(Exception e)
+      {
+         return ("[masked]");
+      }
+   }
+
+   /*******************************************************************************
+    ** Date lower bound, always used with viewer-scoped actions.
+    *******************************************************************************/
+   private static QQueryFilter since(String field, Instant since)
+   {
+      return (new QQueryFilter().withCriteria(field, QCriteriaOperator.GREATER_THAN_OR_EQUALS, since));
+   }
+
+   /*******************************************************************************
+    ** Exact count as the viewer, without authorized scopes.
+    *******************************************************************************/
+   private static int count(String table, QQueryFilter filter) throws QException
+   {
+      return (new CountAction().execute(new CountInput(table).withFilter(filter)).getCount());
+   }
+
+   /*******************************************************************************
+    ** Select only home fields; row and field security remain active.
+    *******************************************************************************/
+   private static List<QRecord> query(String table, QQueryFilter filter, List<String> fields) throws QException
+   {
+      return (new QueryAction().execute(new QueryInput(table).withFilter(filter).withFieldNamesToInclude(new java.util.HashSet<>(fields)).withShouldFetchHeavyFields(true)).getRecords());
+   }
+}

src/main/java/com/kingsrook/qbits/email/app/EmailHomeView.java

@@ -0,0 +1,267 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.app;
+
+
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+import java.util.Locale;
+import com.kingsrook.qbits.email.metadata.EmailEnums;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.template.EmailTemplateEngine;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.ChartData;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Inline styles survive the UI sanitizer. Grids collapse into labelled cards;
+ ** bars shrink with their container and all ordinary text inherits the theme.
+ *******************************************************************************/
+public final class EmailHomeView
+{
+   private static final String WRAP = "min-width:0;max-width:100%;overflow-wrap:anywhere;word-break:break-word;box-sizing:border-box;";
+   private static final String CARD = WRAP + "padding:16px;border:1px solid rgba(127,127,127,.3);border-radius:8px;";
+   private static final String ROW = WRAP + "display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,12rem),1fr));gap:6px 16px;padding:10px 0;border-top:1px solid rgba(127,127,127,.2);";
+   private static final String OK = "#2e9e5b";
+   private static final String FAIL = "#d64545";
+   private static final DateTimeFormatter WHEN = DateTimeFormatter.ofPattern("MMM d, HH:mm 'UTC'", Locale.ENGLISH).withZone(ZoneOffset.UTC);
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailHomeView()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** One ordered home with real, viewer-scoped data supplied by EmailHome.
+    *******************************************************************************/
+   public static String render(List<Integer> totals, ChartData hourly, List<QRecord> messages, ChartData suppressions)
+   {
+      return (render(totals, hourly, messages, suppressions, List.of()));
+   }
+
+
+
+   /*******************************************************************************
+    ** The same home with the Setup card first (email admins), when there are items.
+    *******************************************************************************/
+   public static String render(List<Integer> totals, ChartData hourly, List<QRecord> messages, ChartData suppressions, List<EmailSetupStatus.Item> setup)
+   {
+      StringBuilder html = new StringBuilder("<div style=\"" + WRAP + "display:flex;flex-direction:column;gap:16px;color:inherit;line-height:1.4\">");
+      setup(html, setup);
+      html.append("<div style=\"" + WRAP + "display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,9rem),1fr));gap:12px\">");
+      List<String> labels = List.of("Sent (24 h)", "Delivered (24 h)", "Dead letters (24 h)", "Bounced (7 d)", "Complaints (7 d)", "Suppressed addresses");
+      for(int i = 0; i < labels.size(); i++)
+      {
+         html.append("<div style=\"").append(CARD).append("padding:12px\"><div style=\"font-size:1.6rem;font-weight:600;line-height:1.2;")
+            .append(i >= 2 && i <= 4 && totals.get(i) > 0 ? "color:" + FAIL : "color:inherit").append("\">")
+            .append(String.format(Locale.ENGLISH, "%,d", totals.get(i))).append("</div><div style=\"font-size:.85rem;opacity:.75\">")
+            .append(labels.get(i)).append("</div></div>");
+      }
+      html.append("</div>");
+      bars(html, "Sends per hour, last 24 hours", hourly);
+      messages(html, messages);
+      bars(html, "Suppressions added, last 30 days", suppressions);
+      return (html.append("</div>").toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** The Setup card: each part of Email, set up or not, and the next step, linked
+    ** to its table.
+    *******************************************************************************/
+   private static void setup(StringBuilder html, List<EmailSetupStatus.Item> items)
+   {
+      if(items.isEmpty())
+      {
+         return;
+      }
+      section(html, "Setup");
+      long todo = items.stream().filter(item -> item.state() == EmailSetupStatus.State.TODO).count();
+      html.append("<p style=\"margin:0 0 8px;opacity:.75\">").append(todo == 0 ? "Everything Email needs is set up." : todo + (todo == 1 ? " item needs" : " items need") + " attention.").append("</p>");
+      for(EmailSetupStatus.Item item : items)
+      {
+         String color = switch(item.state())
+         {
+            case OK -> OK;
+            case TODO -> FAIL;
+            case DEFAULT -> "#d97706";
+            case OPTIONAL -> "#808080";
+         };
+         String label = switch(item.state())
+         {
+            case OK -> "Set up";
+            case TODO -> "Needs setup";
+            case DEFAULT -> "Using defaults";
+            case OPTIONAL -> "Optional";
+         };
+         String name = item.tableName() == null ? esc(item.label()) : "<a style=\"color:inherit\" href=\"/app/" + esc(item.tableName()) + "\">" + esc(item.label()) + "</a>";
+         html.append("<div style=\"").append(ROW).append("\">")
+            .append(cell("Part", "<strong>" + name + "</strong><br><span style=\"color:" + color + "\">" + label + "</span>"))
+            .append(cell("Status", esc(item.detail())))
+            .append(cell("Next step", esc(item.nextStep() == null ? "Nothing to do" : item.nextStep()))).append("</div>");
+      }
+      html.append("</section>");
+   }
+
+
+
+   /*******************************************************************************
+    ** A bounded stacked bar chart, including exact values in each bar's title.
+    *******************************************************************************/
+   private static void bars(StringBuilder html, String title, ChartData chart)
+   {
+      section(html, title);
+      var data = chart.getChartData();
+      int max = 0;
+      for(int i = 0; i < data.getLabels().size(); i++)
+      {
+         int total = 0;
+         for(var dataset : data.getDatasets())
+         {
+            total += dataset.getData().get(i).intValue();
+         }
+         max = Math.max(max, total);
+      }
+      if(max == 0)
+      {
+         html.append("<p style=\"margin:0;opacity:.75\">").append(esc(chart.getSublabel())).append("</p></section>");
+         return;
+      }
+      html.append("<div style=\"font-size:.75rem;opacity:.75\">Peak ").append(max).append("</div>")
+         .append("<div role=\"img\" aria-label=\"").append(esc(title)).append("; stacked counts, UTC\" style=\"")
+         .append(WRAP).append("display:flex;align-items:flex-end;gap:2px;height:140px;width:100%\">");
+      for(int i = 0; i < data.getLabels().size(); i++)
+      {
+         StringBuilder description = new StringBuilder(data.getLabels().get(i));
+         for(var dataset : data.getDatasets())
+         {
+            description.append("; ").append(dataset.getLabel()).append(": ").append(dataset.getData().get(i));
+         }
+         html.append("<div title=\"").append(esc(description.toString())).append("\" style=\"flex:1 1 0;min-width:0;height:100%;display:flex;flex-direction:column-reverse\">");
+         for(var dataset : data.getDatasets())
+         {
+            html.append("<div style=\"background:").append(dataset.getColor()).append(";height:")
+               .append(String.format(Locale.ROOT, "%.3f", 100.0 * dataset.getData().get(i).doubleValue() / max)).append("%\"></div>");
+         }
+         html.append("</div>");
+      }
+      html.append("</div><div style=\"display:flex;justify-content:space-between;gap:8px;min-width:0;font-size:.75rem;opacity:.75;margin-top:4px\">");
+      for(int i : new int[] {0, data.getLabels().size() / 2, data.getLabels().size() - 1})
+      {
+         html.append("<span>").append(esc(data.getLabels().get(i))).append("</span>");
+      }
+      html.append("</div><div style=\"display:flex;flex-wrap:wrap;gap:8px 16px;min-width:0;font-size:.8rem;margin-top:8px\">");
+      for(var dataset : data.getDatasets())
+      {
+         html.append("<span><span style=\"display:inline-block;width:.7rem;height:.7rem;margin-right:5px;background:")
+            .append(dataset.getColor()).append("\"></span>").append(esc(dataset.getLabel())).append("</span>");
+      }
+      html.append("<span style=\"opacity:.75\">UTC</span></div></section>");
+   }
+
+
+
+   /*******************************************************************************
+    ** The whole row is a link. Labelled columns stack as cards on narrow screens.
+    *******************************************************************************/
+   private static void messages(StringBuilder html, List<QRecord> messages)
+   {
+      section(html, "Recent messages");
+      if(messages.isEmpty())
+      {
+         html.append("<p style=\"margin:0;opacity:.75\">No messages yet.</p>");
+      }
+      for(QRecord message : messages)
+      {
+         String subject = Boolean.TRUE.equals(message.getValueBoolean("phiApproved")) || "[encrypted]".equals(message.getValueString("subject"))
+            ? "Secure message" : value(message, "subject", "Message " + message.getValueInteger("id"));
+         String status = message.getValueString("status");
+         html.append("<a href=\"/app/").append(EmailTables.MESSAGE).append('/').append(message.getValueInteger("id"))
+            .append("\" style=\"").append(ROW).append("color:inherit;text-decoration:none\">")
+            .append(cell("When", esc(when(message.getValueInstant("createDate")))))
+            .append(cell("To", esc(EmailHome.mask(message.getValueString("toAddresses")))))
+            .append(cell("Subject", esc(subject)))
+            .append(cell("Status", esc(status == null ? "Unknown" : EmailEnums.MessageStatus.valueOf(status).getPossibleValueLabel())))
+            .append("</a>");
+      }
+      html.append("</section>");
+   }
+
+
+
+   /*******************************************************************************
+    ** One bordered section, using the surrounding theme's text colour.
+    *******************************************************************************/
+   private static void section(StringBuilder html, String title)
+   {
+      html.append("<section style=\"").append(CARD).append("\"><h3 style=\"margin:0 0 12px;font-size:1rem;font-weight:600\">").append(esc(title)).append("</h3>");
+   }
+
+
+
+   /*******************************************************************************
+    ** A labelled, shrinkable cell that remains understandable when stacked.
+    *******************************************************************************/
+   private static String cell(String label, String content)
+   {
+      return ("<div style=\"" + WRAP + "\"><span style=\"display:block;font-size:.75rem;opacity:.65\">" + esc(label) + "</span> " + content + "</div>");
+   }
+
+
+
+   /*******************************************************************************
+    ** Compact UTC dates, with an honest missing value.
+    *******************************************************************************/
+   private static String when(Instant instant)
+   {
+      return (instant == null ? "None" : WHEN.format(instant));
+   }
+
+
+
+   /*******************************************************************************
+    ** Blank fields use a human-readable fallback.
+    *******************************************************************************/
+   private static String value(QRecord row, String field, String fallback)
+   {
+      String value = row.getValueString(field);
+      return (value == null || value.isBlank() ? fallback : value);
+   }
+
+
+
+   /*******************************************************************************
+    ** Escape every record-sourced value before inserting HTML.
+    *******************************************************************************/
+   private static String esc(String value)
+   {
+      return (EmailTemplateEngine.escape(value));
+   }
+}

src/main/java/com/kingsrook/qbits/email/app/EmailSetupStatus.java

@@ -0,0 +1,199 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.app;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.email.EmailQBitConfig;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.api.EmailApi;
+import com.kingsrook.qbits.email.api.EmailApiCategory;
+import com.kingsrook.qbits.email.api.EmailApiReadiness;
+import com.kingsrook.qbits.email.api.EmailApiReadinessCheck;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** The Setup card on the Email home: each configuration table, whether it is
+ ** set up, and the next step. It uses the same resolution the sender uses (the
+ ** default provider, the brand lookup, EmailApi.readiness), so it never reports
+ ** a problem the sender would not have.
+ *******************************************************************************/
+public final class EmailSetupStatus
+{
+   /*******************************************************************************
+    ** OK: working. TODO: needs attention. DEFAULT: working on built-in defaults.
+    ** OPTIONAL: a feature that is off until set up.
+    *******************************************************************************/
+   public enum State
+   {
+      OK, TODO, DEFAULT, OPTIONAL
+   }
+
+
+
+   /*******************************************************************************
+    ** One line of the card.
+    *******************************************************************************/
+   public record Item(String label, String tableName, State state, String detail, String nextStep)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailSetupStatus()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Build the items (as the qbit, for an email admin).
+    *******************************************************************************/
+   public static List<Item> load() throws QException
+   {
+      EmailQBitConfig config = EmailRuntime.config();
+      List<Item>      items  = new ArrayList<>();
+
+      ///////////////////////////////////////////////////////////
+      // the provider: the same check a send makes (readiness) //
+      ///////////////////////////////////////////////////////////
+      EmailApiReadiness readiness = EmailApi.readiness(QContext.getQInstance(), EmailApiCategory.TRANSACTIONAL);
+      List<QRecord>     providers = SystemWrites.query(EmailTables.PROVIDER, new QQueryFilter());
+      QRecord           active    = providers.stream().filter(p -> Boolean.TRUE.equals(p.getValueBoolean("enabled")) && Boolean.TRUE.equals(p.getValueBoolean("isDefault")))
+         .findFirst().orElse(null);
+      if(readiness.failed(EmailApiReadinessCheck.PROVIDER_MISSING))
+      {
+         items.add(new Item("Provider", EmailTables.PROVIDER, State.TODO, providers.isEmpty() ? "No provider yet, so nothing can be sent." : "No enabled default provider, so nothing can be sent.",
+            "Add one with New (kind, host or region, from address, and the NAMES of the secret variables), turn on Default, then Send Test Email."));
+      }
+      else if(readiness.failed(EmailApiReadinessCheck.PROVIDER_INVALID))
+      {
+         items.add(new Item("Provider", EmailTables.PROVIDER, State.TODO, "The default provider's configuration is invalid.", "Open it and fix the highlighted settings, then Send Test Email."));
+      }
+      else if(active != null && "UNHEALTHY".equals(active.getValueString("healthStatus")))
+      {
+         items.add(new Item("Provider", EmailTables.PROVIDER, State.TODO, "The default provider is failing. See System Health for its status.",
+            "Check its settings and secret variables, then Send Test Email."));
+      }
+      else
+      {
+         items.add(new Item("Provider", EmailTables.PROVIDER, State.OK, valueOr(active == null ? null : active.getValueString("label"), "The default provider") + " sends mail.", null));
+      }
+
+      ///////////////////////////////////////////////////////////////
+      // sender addresses: the provider's own from address works //
+      ///////////////////////////////////////////////////////////////
+      int senders = SystemWrites.count(EmailTables.SENDER, new QQueryFilter());
+      items.add(senders == 0
+         ? new Item("Sender addresses", EmailTables.SENDER, State.OPTIONAL, "None: the provider's own from address is used.", "Add some if one provider sends as several mailboxes.")
+         : new Item("Sender addresses", EmailTables.SENDER, State.OK, senders + (senders == 1 ? " address." : " addresses."), null));
+
+      //////////////////////////////////////////////////////////////////
+      // brand: the lookup the renderer does (app brand, then default) //
+      //////////////////////////////////////////////////////////////////
+      List<QRecord> brands = SystemWrites.query(EmailTables.BRAND, EmailStore.equal("appName", config.getAppName()));
+      if(brands.isEmpty())
+      {
+         brands = SystemWrites.query(EmailTables.BRAND, EmailStore.equal("isDefault", true));
+      }
+      if(brands.size() > 1)
+      {
+         items.add(new Item("Brands", EmailTables.BRAND, State.TODO, "More than one default brand matches, so branded sends are refused.", "Leave Default Brand on only one."));
+      }
+      else if(brands.isEmpty())
+      {
+         items.add(new Item("Brands", EmailTables.BRAND, State.DEFAULT, "No default brand: emails use the plain neutral look.", "Copy the neutral brand, set your logo, colors and footer, and tick Default Brand."));
+      }
+      else
+      {
+         items.add(new Item("Brands", EmailTables.BRAND, State.OK, valueOr(brands.getFirst().getValueString("label"), "The default brand") + " is the default.", null));
+      }
+
+      ///////////////
+      // templates //
+      ///////////////
+      int templates = SystemWrites.count(EmailTables.TEMPLATE, new QQueryFilter());
+      items.add(templates == 0
+         ? new Item("Templates", EmailTables.TEMPLATE, State.DEFAULT, "No template yet: plain messages can still be sent.", "Other qbits register theirs; add your own with New, then Activate Version.")
+         : new Item("Templates", EmailTables.TEMPLATE, State.OK, templates + (templates == 1 ? " template." : " templates."), null));
+
+      /////////////////////////////////////////////////////
+      // marketing: the same checks as a MARKETING send //
+      /////////////////////////////////////////////////////
+      EmailApiReadiness marketing = EmailApi.readiness(QContext.getQInstance(), EmailApiCategory.MARKETING);
+      List<String>      missing   = new ArrayList<>();
+      if(marketing.failed(EmailApiReadinessCheck.PUBLIC_BASE_URL))
+      {
+         missing.add("a public base URL");
+      }
+      if(marketing.failed(EmailApiReadinessCheck.UNSUBSCRIBE_KEY))
+      {
+         missing.add("the QQQ_EMAIL_UNSUBSCRIBE_KEY variable");
+      }
+      if(marketing.failed(EmailApiReadinessCheck.BRAND_POSTAL_ADDRESS))
+      {
+         missing.add("a default brand with a postal address");
+      }
+      items.add(missing.isEmpty()
+         ? new Item("Marketing email", EmailTables.BRAND, State.OK, "Ready: unsubscribe links, base URL and postal address are set.", null)
+         : new Item("Marketing email", EmailTables.BRAND, State.OPTIONAL, "Off until set up: needs " + String.join(", ", missing) + ".", "Only needed if you send marketing email."));
+
+      //////////////////////////////////////////////////////////
+      // delivery tracking: the provider's webhook secret name //
+      //////////////////////////////////////////////////////////
+      boolean webhook = active != null && valueOr(active.getValueString("webhookSecretEnvName"), "").length() > 0;
+      int     inbox   = SystemWrites.count(EmailTables.INBOX, new QQueryFilter());
+      items.add(webhook
+         ? new Item("Delivery tracking", EmailTables.INBOX, State.OK, inbox == 0 ? "A webhook secret is set; no callback has arrived yet." : inbox + " provider callbacks received.", null)
+         : new Item("Delivery tracking", EmailTables.INBOX, State.OPTIONAL, "Off: the default provider has no webhook secret variable, so bounces and complaints are not tracked.",
+            "Set the provider's webhook secret variable and point the provider at " + config.getWebhookBasePath() + "."));
+
+      int suppressed = SystemWrites.count(EmailTables.SUPPRESSION, new QQueryFilter());
+      items.add(new Item("Suppression list", EmailTables.SUPPRESSION, State.OPTIONAL, suppressed == 0 ? "No blocked addresses yet; bounces, complaints and unsubscribes add them." : suppressed + " blocked addresses.", null));
+
+      items.add(config.getSchedulerName() == null
+         ? new Item("Scheduler", null, State.TODO, "No scheduler is configured, so the outbox is only sent when someone runs Dispatch by hand.", "Set schedulerName in the Email config.")
+         : new Item("Scheduler", null, State.OK, "Dispatch, webhooks, maintenance and retention run on the " + config.getSchedulerName() + " scheduler.", null));
+      return (items);
+   }
+
+
+
+   /*******************************************************************************
+    ** The value, or the fallback when blank.
+    *******************************************************************************/
+   private static String valueOr(String value, String fallback)
+   {
+      return (value == null || value.isBlank() ? fallback : value);
+   }
+
+}

src/main/java/com/kingsrook/qbits/email/bridge/EmailOutboxMessagingProvider.java

@@ -59,7 +59,8 @@ public class EmailOutboxMessagingProvider implements MessagingProviderInterface
       {
          throw (new QException("Email attachments are not supported in part 1"));
       }
-      EmailRequest request = new EmailRequest().withSubject(input.getSubject());
+      EmailRequest request = input instanceof EmailTemplatedMessageInput templated && templated.getEmailRequest() != null
+         ? templated.getEmailRequest() : new EmailRequest().withSubject(input.getSubject());
       parties(request, input.getTo(), EmailPartyRole.TO);
       parties(request, input.getFrom(), EmailPartyRole.FROM);
       if(input.getContentList() != null)

src/main/java/com/kingsrook/qbits/email/bridge/EmailTemplatedMessageInput.java

@@ -0,0 +1,52 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.bridge;
+
+
+import com.kingsrook.qbits.email.outbox.EmailRequest;
+import com.kingsrook.qqq.backend.core.model.actions.messaging.SendMessageInput;
+
+
+/*******************************************************************************
+ ** Optional typed template payload for core SendMessageAction bridge callers.
+ ** Plain SendMessageInput remains an ad-hoc message for backwards compatibility.
+ *******************************************************************************/
+public class EmailTemplatedMessageInput extends SendMessageInput
+{
+   private EmailRequest emailRequest;
+
+   /*******************************************************************************
+    ** Set schema variables and record references for the normal validated API.
+    *******************************************************************************/
+   public EmailTemplatedMessageInput withEmailRequest(EmailRequest request)
+   {
+      emailRequest = request;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** The caller's template request; party fields can still come from core input.
+    *******************************************************************************/
+   public EmailRequest getEmailRequest()
+   {
+      return (emailRequest);
+   }
+}

src/main/java/com/kingsrook/qbits/email/delivery/EmailAlerts.java

@@ -35,6 +35,7 @@ import com.kingsrook.qqq.backend.core.alerts.QAlerts;
  *******************************************************************************/
 public final class EmailAlerts
 {
+   public static final String COMPLAINT = "email.complaint";
    public static final String UNHEALTHY = "email.provider.unhealthy";
    public static final String DEAD_LETTER = "email.message.dead-letter";
 
@@ -50,7 +51,9 @@ public final class EmailAlerts
     *******************************************************************************/
    public static List<QAlertTypeMetaData> types()
    {
-      return (List.of(new QAlertTypeMetaData().withName(UNHEALTHY).withLabel("Email provider unhealthy").withDefaultSeverity(AlertSeverity.ERROR)
+      return (List.of(new QAlertTypeMetaData().withName(COMPLAINT).withLabel("Email complaints").withDefaultSeverity(AlertSeverity.WARNING)
+            .withSubjectTableName(EmailTables.EVENT).withVisibilityPermission("email.view").withSourceName("email"),
+         new QAlertTypeMetaData().withName(UNHEALTHY).withLabel("Email provider unhealthy").withDefaultSeverity(AlertSeverity.ERROR)
             .withSubjectTableName(EmailTables.PROVIDER).withVisibilityPermission("email.admin").withSourceName("email"),
          new QAlertTypeMetaData().withName(DEAD_LETTER).withLabel("Email dead letters").withDefaultSeverity(AlertSeverity.WARNING)
             .withSubjectTableName(EmailTables.MESSAGE).withVisibilityPermission("email.view").withSourceName("email")));
@@ -62,7 +65,11 @@ public final class EmailAlerts
    public static void raise(String type, Integer providerId)
    {
       String key = "provider:" + providerId + (DEAD_LETTER.equals(type) ? ":" + EmailRuntime.clock().instant().getEpochSecond() / 3600 : "");
-      QAlerts.raise(new AlertSignal(type).withDedupKey(key).withTitle(UNHEALTHY.equals(type) ? "Email provider unhealthy" : "Email message dead-lettered")
+      if(COMPLAINT.equals(type))
+      {
+         key = "complaints:" + EmailRuntime.clock().instant().getEpochSecond() / 86400;
+      }
+      QAlerts.raise(new AlertSignal(type).withDedupKey(key).withTitle(COMPLAINT.equals(type) ? "More than three email complaints in 24 hours" : UNHEALTHY.equals(type) ? "Email provider unhealthy" : "Email message dead-lettered")
          .withSummary("Review the Email tables for status and retry actions."));
    }
 

src/main/java/com/kingsrook/qbits/email/delivery/EmailDispatcher.java

@@ -67,7 +67,7 @@ public class EmailDispatcher
     *******************************************************************************/
    public EmailDispatcher()
    {
-      this(new EmailTransportRegistry());
+      this(EmailRuntime.config() == null ? new EmailTransportRegistry() : EmailRuntime.config().newTransportRegistry());
    }
 
    /*******************************************************************************
@@ -201,6 +201,10 @@ public class EmailDispatcher
       EmailTransportException error = null;
       try
       {
+         if(Boolean.TRUE.equals(claim.message().getValueBoolean("phiApproved")))
+         {
+            com.kingsrook.qbits.email.template.EmailTemplateRenderer.checkProvider(claim.provider());
+         }
          result = transports.get(claim.provider().getValueString("kind")).send(envelope(claim.message()), new EmailProviderSettings(claim.provider(), EmailRuntime.config()));
       }
       catch(EmailTransportException e)
@@ -346,9 +350,9 @@ public class EmailDispatcher
          {
             safeError = "Credentials missing or refused";
          }
-         if(error != null && "Provider transport not available until phase (b)".equals(error.getMessage()))
+         if(error != null && "Gmail API sending is specified but not built; use GMAIL_SMTP".equals(error.getMessage()))
          {
-            safeError = "Provider transport not available until phase (b)";
+            safeError = "Gmail API sending is specified but not built; use GMAIL_SMTP";
          }
          EmailStore.update(EmailTables.ATTEMPT, new QRecord().withValue("id", claim.attempt().getValue("id"))
             .withValue("outcome", success ? "SUCCEEDED" : providerLevel ? "PROVIDER_FAILURE" : permanent ? "PERMANENT_FAILURE" : "TRANSIENT_FAILURE")
@@ -447,10 +451,30 @@ public class EmailDispatcher
     *******************************************************************************/
    private static EmailEnvelope envelope(QRecord message)
    {
-      return (new EmailEnvelope().withMessageId(message.getValueString("id")).withFrom(message.getValueString("fromAddress"))
+      return (new EmailEnvelope().withMessageId(message.getValueString("id")).withRfcMessageId(message.getValueString("rfcMessageId")).withFrom(message.getValueString("fromAddress"))
          .withTo(split(message.getValueString("toAddresses"))).withCc(split(message.getValueString("ccAddresses"))).withBcc(split(message.getValueString("bccAddresses")))
-         .withReplyTo(message.getValueString("replyTo")).withSubject(message.getValueString("subject"))
-         .withHtmlBody(message.getValueString("htmlBody")).withTextBody(message.getValueString("textBody")));
+         .withReplyTo(message.getValueString("replyTo")).withSubject(content(message, "subject"))
+         .withHtmlBody(content(message, "htmlBody"))
+         .withTextBody(content(message, "textBody"))
+         .withHeaders(message.getValueString("unsubscribeUrl") == null ? java.util.Map.of() : java.util.Map.of("List-Unsubscribe", "<" + message.getValueString("unsubscribeUrl") + ">", "List-Unsubscribe-Post", "List-Unsubscribe=One-Click")));
+   }
+
+   /*******************************************************************************
+    ** Only policy-marked messages may invoke body decryption. A caller-supplied
+    ** enc:v1 string in ad-hoc content is text, never a decryption capability.
+    *******************************************************************************/
+   private static String content(QRecord message, String field)
+   {
+      String value = message.getValueString(field);
+      if(!Boolean.TRUE.equals(message.getValueBoolean("phiApproved")))
+      {
+         return (value);
+      }
+      if(value != null && !value.startsWith("enc:v1:"))
+      {
+         throw (new IllegalArgumentException("Protected email content must be encrypted"));
+      }
+      return (com.kingsrook.qbits.email.phi.EmailBodyEncryption.decrypt(value, field, message.getValueString("id")));
    }
 
    /*******************************************************************************

src/main/java/com/kingsrook/qbits/email/health/EmailHealthChecks.java

@@ -0,0 +1,223 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.health;
+
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.api.EmailApi;
+import com.kingsrook.qbits.email.api.EmailApiCategory;
+import com.kingsrook.qbits.email.api.EmailApiReadinessCheck;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.health.HealthCategory;
+import com.kingsrook.qqq.backend.core.health.HealthCheck;
+import com.kingsrook.qqq.backend.core.health.HealthCheckInput;
+import com.kingsrook.qqq.backend.core.health.HealthCheckKind;
+import com.kingsrook.qqq.backend.core.health.HealthCheckMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthCheckOutcome;
+import com.kingsrook.qqq.backend.core.health.HealthCheckSupplier;
+import com.kingsrook.qqq.backend.core.health.HealthCheckSupplierMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthChecksMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthDetails;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+
+
+/*******************************************************************************
+ ** Central health adapters reuse readiness and passive delivery state; never send.
+ *******************************************************************************/
+public class EmailHealthChecks implements HealthCheckSupplier
+{
+   /*******************************************************************************
+    ** Register without querying data during metadata production.
+    *******************************************************************************/
+   public static void register(QInstance instance)
+   {
+      HealthChecksMetaData registry = HealthChecksMetaData.ofOrWithNew(instance);
+      if(registry.getChecks().stream().noneMatch(check -> "email.readiness".equals(check.getName())))
+      {
+         registry.withCheck(definition("email.readiness", EmailHealthChecks::readiness));
+      }
+      if(registry.getSuppliers().stream().noneMatch(supplier -> "email.provider".equals(supplier.getNamePrefix())))
+      {
+         registry.withSupplier(new HealthCheckSupplierMetaData().withNamePrefix("email.provider").withComponent("email")
+            .withSupplier(new QCodeReference(EmailHealthChecks.class)));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider primary keys are integers, so their names are already lowercase.
+    ** Capture only identity; each execution rereads current state.
+    *******************************************************************************/
+   @Override
+   public List<HealthCheckMetaData> supply(QInstance instance) throws QException
+   {
+      List<HealthCheckMetaData> checks = new ArrayList<>();
+      for(QRecord provider : providers(EmailStore.equal("enabled", true), Set.of("id")))
+      {
+         Integer id = provider.getValueInteger("id");
+         checks.add(definition("email.provider." + id, input -> provider(id, input)));
+      }
+      return (checks);
+   }
+
+
+
+   /*******************************************************************************
+    ** Bound execution cooperatively around existing reads. Core also enforces
+    ** the hard timeout. Exception text may contain PHI or secrets: omit it.
+    *******************************************************************************/
+   private static HealthCheckMetaData definition(String name, HealthCheck check)
+   {
+      return (new HealthCheckMetaData().withName(name).withLabel(name).withComponent("email")
+         .withCategory(HealthCategory.EMAIL).withKind(HealthCheckKind.DEPENDENCY)
+         .withIntervalSeconds(EmailHealthWidget.CHECK_INTERVAL_MINUTES * 60).withTimeoutMs(5000).withCheckInstance(input ->
+         {
+            try
+            {
+               requireTime(input);
+               HealthCheckOutcome outcome = check.run(input);
+               requireTime(input);
+               return (outcome);
+            }
+            catch(Exception e)
+            {
+               return (HealthCheckOutcome.down("Email health check failed: " + e.getClass().getSimpleName()));
+            }
+         }));
+   }
+
+
+
+   /*******************************************************************************
+    ** Aggregate all category preflights, exposing enum names instead of reasons.
+    *******************************************************************************/
+   private static HealthCheckOutcome readiness(HealthCheckInput input) throws QException
+   {
+      Set<EmailApiReadinessCheck> failed = EnumSet.noneOf(EmailApiReadinessCheck.class);
+      boolean ready = true;
+      for(EmailApiCategory category : EmailApiCategory.values())
+      {
+         requireTime(input);
+         var readiness = EmailApi.readiness(input.getQInstance(), category);
+         ready &= readiness.ready();
+         failed.addAll(readiness.failedChecks());
+      }
+      if(ready)
+      {
+         return (HealthCheckOutcome.up("Email configuration ready").withDetails(new HealthDetails().withValue("failedChecks", "")));
+      }
+      var config = EmailRuntime.config(input.getQInstance());
+      String app = config == null || config.getAppLabel() == null ? "Email" : config.getAppLabel();
+      List<String> fixes = failed.stream().map(check -> fix(check, app)).toList();
+      String message = "Email configuration incomplete: " + String.join(" ", fixes);
+      String details = String.join("\n", fixes);
+      return (HealthCheckOutcome.degraded(message.length() > 500 ? message.substring(0, 500) : message)
+         .withDetails(new HealthDetails().withValue("failedChecks", failed.stream().map(Enum::name).collect(Collectors.joining(",")))
+            .withValue("howToFix", details.length() > 4000 ? details.substring(0, 4000) : details)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Plain-words statement of one missing prerequisite and where to set it.
+    *******************************************************************************/
+   private static String fix(EmailApiReadinessCheck check, String app)
+   {
+      return (switch(check)
+      {
+         case NOT_INSTALLED -> "The Email qbit is not installed.";
+         case PROVIDER_MISSING -> "No enabled default email provider (" + app + " > Provider: add one and tick Enabled and Is Default).";
+         case PROVIDER_INVALID -> "The default email provider settings are invalid (" + app + " > Provider: open the default provider and correct it).";
+         case PHI_PROVIDER -> "PHI email needs a PHI-enabled provider with open and click tracking off (" + app + " > Provider).";
+         case PUBLIC_BASE_URL -> "Public base URL is not set (the publicBaseUrl setting in the Email qbit config). Needed for marketing unsubscribe links; transactional email is unaffected.";
+         case UNSUBSCRIBE_KEY -> "The QQQ_EMAIL_UNSUBSCRIBE_KEY secret is not set (deployment environment variable). Needed for marketing unsubscribe links; transactional email is unaffected.";
+         case BRAND_POSTAL_ADDRESS -> "Brand postal address is not set (" + app + " > Brand > open the default brand > Postal address). Needed for marketing email footers; transactional email is unaffected.";
+         case BODY_KEY -> "The QQQ_EMAIL_BODY_KEY secret is not set (deployment environment variable). Needed for PHI email.";
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** The transport SPI has no non-sending connectivity method. Passive state
+    ** is the only signal; never read or publish lastFailureMessage.
+    *******************************************************************************/
+   private static HealthCheckOutcome provider(Integer id, HealthCheckInput input) throws QException
+   {
+      List<QRecord> rows = providers(EmailStore.equal("id", id).withLimit(1), Set.of("id", "enabled", "healthStatus", "lastSuccessDate"));
+      requireTime(input);
+      if(rows.isEmpty() || !Boolean.TRUE.equals(rows.getFirst().getValueBoolean("enabled")))
+      {
+         return (HealthCheckOutcome.unknown("Provider disabled or removed"));
+      }
+      QRecord row = rows.getFirst();
+      String state = row.getValueString("healthStatus");
+      HealthCheckOutcome outcome = "HEALTHY".equals(state) ? HealthCheckOutcome.up("Passive provider state healthy")
+         : "UNHEALTHY".equals(state) ? HealthCheckOutcome.down("Passive provider state unhealthy; see provider record")
+         : HealthCheckOutcome.unknown("Passive provider state unavailable");
+      HealthDetails details = new HealthDetails().withValue("providerId", id).withValue("passive", true);
+      Instant lastSuccess = row.getValueInstant("lastSuccessDate");
+      if(lastSuccess != null)
+      {
+         details.withValue("lastSuccessDate", lastSuccess);
+      }
+      return (outcome.withDetails(details));
+   }
+
+
+
+   /*******************************************************************************
+    ** Select only needed fields under the qbit's established system read scope.
+    *******************************************************************************/
+   private static List<QRecord> providers(QQueryFilter filter, Set<String> fields) throws QException
+   {
+      return (SystemWrites.call(() -> new QueryAction().execute(new QueryInput(EmailTables.PROVIDER).withFilter(filter)
+         .withFieldNamesToInclude(fields).withShouldFetchHeavyFields(false).withShouldOmitHiddenFields(false)).getRecords()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Do not start further work after the runner's deadline or cancellation.
+    *******************************************************************************/
+   private static void requireTime(HealthCheckInput input) throws QException
+   {
+      if(Thread.currentThread().isInterrupted() || (input.getDeadline() != null && !Instant.now().isBefore(input.getDeadline())))
+      {
+         throw (new QException("Health check deadline exceeded"));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/health/EmailHealthWidget.java

@@ -0,0 +1,108 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.health;
+
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Set;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.health.HealthMetaDataProvider;
+import com.kingsrook.qqq.backend.core.health.HealthStatus;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.StatisticsData;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+
+
+/*******************************************************************************
+ ** One standard status line linking to central checks; no provider diagnostics.
+ *******************************************************************************/
+public class EmailHealthWidget extends AbstractWidgetRenderer
+{
+   public static final String NOT_CHECKED = "Not checked yet";
+
+   //////////////////////////////////////////////////////////////////////////////
+   // the interval of the email health checks (EmailHealthChecks), in minutes   //
+   //////////////////////////////////////////////////////////////////////////////
+   static final int CHECK_INTERVAL_MINUTES = 5;
+
+
+
+   /*******************************************************************************
+    ** Human words for a health status; unknown means no check has reported yet.
+    *******************************************************************************/
+   static String wording(String status)
+   {
+      return (switch(status)
+      {
+         case "UP" -> "Healthy";
+         case "DEGRADED" -> "Degraded";
+         case "DOWN" -> "Down";
+         default -> NOT_CHECKED;
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Read the persisted rollup as the viewer, preserving health permissions.
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      String status = HealthStatus.UNKNOWN.name();
+      boolean installed = QContext.getQInstance().getTable(HealthMetaDataProvider.COMPONENT_TABLE) != null;
+      boolean readable = installed && PermissionsHelper.hasTablePermission(input, HealthMetaDataProvider.COMPONENT_TABLE, TablePermissionSubType.READ);
+      if(readable)
+      {
+         List<QRecord> rows = new QueryAction().execute(new QueryInput(HealthMetaDataProvider.COMPONENT_TABLE)
+            .withFilter(EmailStore.equal("name", "email").withLimit(1)).withFieldNamesToInclude(Set.of("status"))).getRecords();
+         if(!rows.isEmpty())
+         {
+            String stored = rows.getFirst().getValueString("status");
+            for(HealthStatus candidate : HealthStatus.values())
+            {
+               if(candidate.name().equals(stored))
+               {
+                  status = candidate.name();
+               }
+            }
+         }
+      }
+      String context = !installed ? "Email - health monitoring not configured" : readable ? "Email - System Health. Checks run every " + CHECK_INTERVAL_MINUTES + " minutes" : "Email - health access required";
+      StatisticsData data = new StatisticsData().withCount(wording(status)).withCountFontSize("1rem").withCountContext(context);
+      if(readable)
+      {
+         data.withCountURL("/app/health_check?filter=" + URLEncoder.encode(JsonUtils.toJson(EmailStore.equal("component", "email")), StandardCharsets.UTF_8));
+      }
+      return (new RenderWidgetOutput(data));
+   }
+}

src/main/java/com/kingsrook/qbits/email/metadata/EmailEnums.java

@@ -130,7 +130,7 @@ public final class EmailEnums
       @Override
       public String getPossibleValueLabel()
       {
-         return (name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
+         return (this == RETRY_WAIT ? "Waiting to retry" : name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
       }
    }
 
@@ -202,7 +202,8 @@ public final class EmailEnums
    {
       MARKDOWN,
       MJML,
-      HTML;
+      HTML,
+      CRM_LEGACY;
 
       /*******************************************************************************
        ** Stable database value.
@@ -312,4 +313,88 @@ public final class EmailEnums
          return (name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
       }
    }
+
+
+
+   /*******************************************************************************
+    ** InboxStatus values.
+    *******************************************************************************/
+   public enum InboxStatus implements PossibleValueEnum<String>
+   {
+      PENDING, PROCESSED, FAILED, IGNORED;
+
+      /*******************************************************************************
+       ** Stable stored identifier.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueId()
+      {
+         return (name());
+      }
+
+      /*******************************************************************************
+       ** Display label.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueLabel()
+      {
+         return (name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** EventType values.
+    *******************************************************************************/
+   public enum EventType implements PossibleValueEnum<String>
+   {
+      DELIVERED, DEFERRED, BOUNCED, COMPLAINED, OPENED, CLICKED, UNSUBSCRIBED, REJECTED;
+
+      /*******************************************************************************
+       ** Stable stored identifier.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueId()
+      {
+         return (name());
+      }
+
+      /*******************************************************************************
+       ** Display label.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueLabel()
+      {
+         return (name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** BounceType values.
+    *******************************************************************************/
+   public enum BounceType implements PossibleValueEnum<String>
+   {
+      HARD, SOFT, UNDETERMINED;
+
+      /*******************************************************************************
+       ** Stable stored identifier.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueId()
+      {
+         return (name());
+      }
+
+      /*******************************************************************************
+       ** Display label.
+       *******************************************************************************/
+      @Override
+      public String getPossibleValueLabel()
+      {
+         return (name().charAt(0) + name().substring(1).toLowerCase(java.util.Locale.ROOT).replace('_', ' '));
+      }
+   }
 }

src/main/java/com/kingsrook/qbits/email/metadata/EmailTableCustomizers.java

@@ -21,23 +21,32 @@
 package com.kingsrook.qbits.email.metadata;
 
 
+import java.io.Serializable;
 import java.util.ArrayList;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.Set;
 import com.kingsrook.qbits.email.EmailQBitConfig;
 import com.kingsrook.qbits.email.EmailRuntime;
 import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
 import com.kingsrook.qbits.email.permissions.EmailPermissions;
+import com.kingsrook.qbits.email.support.EmailStore;
 import com.kingsrook.qbits.email.support.SystemWrites;
 import com.kingsrook.qbits.email.transport.EmailProviderSettings;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
 import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.statusmessages.BadInputStatusMessage;
 import jakarta.mail.internet.InternetAddress;
@@ -77,6 +86,37 @@ public final class EmailTableCustomizers
    {
       List<String> errors = new ArrayList<>();
       String kind = row.getValueString("kind");
+      if("GMAIL_API".equals(kind))
+      {
+         errors.add("Gmail API sending is specified but not built; use GMAIL_SMTP");
+      }
+      if(List.of("POSTMARK", "SENDGRID", "MAILGUN", "GMAIL_SMTP").contains(kind == null ? "" : kind)
+         && (row.getValueString("secretEnvName") == null || row.getValueString("secretEnvName").isBlank()))
+      {
+         errors.add("Provider needs a secret environment name");
+      }
+      if("GMAIL_SMTP".equals(kind))
+      {
+         if(row.getValueString("usernameEnvName") == null || row.getValueString("usernameEnvName").isBlank())
+         {
+            errors.add("Gmail SMTP needs an account address environment name");
+         }
+         if(row.getValueString("security") != null && !"STARTTLS".equals(row.getValueString("security")))
+         {
+            errors.add("Gmail SMTP requires STARTTLS");
+         }
+      }
+      if("MAILGUN".equals(kind))
+      {
+         if(!EmailProviderSettings.validSendingDomain(row.getValueString("sendingDomain")))
+         {
+            errors.add("Mailgun needs a valid sending domain");
+         }
+         if(!List.of("US", "EU").contains(row.getValueString("region") == null ? "" : row.getValueString("region")))
+         {
+            errors.add("Mailgun region must be US or EU");
+         }
+      }
       if(("SMTP".equals(kind) || "GMAIL_SMTP".equals(kind))
          && !new EmailProviderSettings(row, config).allowsSmtpAuth())
       {
@@ -166,6 +206,13 @@ public final class EmailTableCustomizers
                   record.setValue(field, null);
                }
             }
+            String sendingDomain = merged.getValueString("sendingDomain");
+            if(sendingDomain != null && !sendingDomain.isBlank() && merged.getValue("id") != null
+               && SystemWrites.query(EmailTables.SENDER, EmailStore.equal("providerId", merged.getValueInteger("id")), null).stream()
+                  .anyMatch(s -> !sendingDomain.equalsIgnoreCase(s.getValueString("address").substring(s.getValueString("address").lastIndexOf('@') + 1))))
+            {
+               record.addError(new BadInputStatusMessage("Sender addresses must match the sending domain"));
+            }
             resulting.removeIf(r -> Objects.equals(r.getValue("id"), record.getValue("id")));
             resulting.add(merged);
             record.setValue("defaultSlot", Boolean.TRUE.equals(merged.getValueBoolean("enabled")) && Boolean.TRUE.equals(merged.getValueBoolean("isDefault")) ? 1 : null);
@@ -187,9 +234,16 @@ public final class EmailTableCustomizers
       {
          for(QRecord row : records)
          {
-            if(!SystemWrites.query(EmailTables.MESSAGE, com.kingsrook.qbits.email.support.EmailStore.equal("providerId", row.getValueInteger("id")).withLimit(1), input.getTransaction()).isEmpty())
+            //////////////////////////////////////////////////////////////////
+            // the same history the RESTRICT foreign keys protect (docs/ddl) //
+            //////////////////////////////////////////////////////////////////
+            for(String history : List.of(EmailTables.MESSAGE, EmailTables.ATTEMPT, EmailTables.EVENT, EmailTables.INBOX))
             {
-               row.addError(new BadInputStatusMessage("Providers with message history cannot be deleted; disable the provider instead"));
+               if(!SystemWrites.query(history, EmailStore.equal("providerId", row.getValueInteger("id")).withLimit(1), input.getTransaction()).isEmpty())
+               {
+                  row.addError(new BadInputStatusMessage("Providers with message history cannot be deleted; disable the provider instead"));
+                  break;
+               }
             }
          }
          List<QRecord> remaining = new ArrayList<>(SystemWrites.query(EmailTables.PROVIDER, new QQueryFilter(), input.getTransaction()));
@@ -199,6 +253,13 @@ public final class EmailTableCustomizers
          {
             records.forEach(r -> r.addError(new BadInputStatusMessage("Choose another enabled default before deleting this provider")));
          }
+         for(QRecord row : records)
+         {
+            if(!preview && row.getErrors().isEmpty())
+            {
+               SystemWrites.delete(EmailTables.SENDER, EmailStore.equal("providerId", row.getValueInteger("id")), input.getTransaction());
+            }
+         }
          return (records);
       }
 
@@ -208,6 +269,11 @@ public final class EmailTableCustomizers
       @Override
       public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records)
       {
+         for(QRecord row : records)
+         {
+            String label = row.getValueString("label");
+            row.setRecordLabel(label == null || label.isBlank() ? row.getValueString("name") : label);
+         }
          if(!SystemWrites.active())
          {
             for(QRecord row : records)
@@ -236,6 +302,106 @@ public final class EmailTableCustomizers
       }
    }
 
+   /*******************************************************************************
+    ** Sender addresses: canonical lowercase address, the provider's sending domain,
+    ** unique per provider and at most one enabled default per provider.
+    *******************************************************************************/
+   public static class SenderAddressCustomizer implements TableCustomizerInterface
+   {
+      /*******************************************************************************
+       ** Validate each row against its provider and the resulting set of rows.
+       *******************************************************************************/
+      @Override
+      public List<QRecord> preInsertOrUpdate(AbstractActionInput input, List<QRecord> records, boolean preview, Optional<List<QRecord>> oldRecords) throws QException
+      {
+         if(SystemWrites.active())
+         {
+            return (records);
+         }
+         QBackendTransaction transaction = input instanceof InsertInput insert ? insert.getTransaction() : input instanceof UpdateInput update ? update.getTransaction() : null;
+         List<QRecord> resulting = new ArrayList<>();
+         Set<Serializable> providerIds = new LinkedHashSet<>();
+         for(QRecord record : records)
+         {
+            QRecord merged = effective(record, oldRecords);
+            if(record.getValueString("address") != null)
+            {
+               try
+               {
+                  String text = record.getValueString("address");
+                  if(text.contains("\r") || text.contains("\n"))
+                  {
+                     throw (new IllegalArgumentException("Sender address must not contain line breaks"));
+                  }
+                  InternetAddress address = new InternetAddress(text, true);
+                  address.validate();
+                  record.setValue("address", address.getAddress().toLowerCase(Locale.ROOT));
+                  merged.setValue("address", record.getValue("address"));
+               }
+               catch(Exception e)
+               {
+                  record.addError(new BadInputStatusMessage("A valid sender address is required"));
+               }
+            }
+            String name = merged.getValueString("displayName");
+            if(name != null && (name.contains("\r") || name.contains("\n")))
+            {
+               record.addError(new BadInputStatusMessage("Display name must not contain line breaks"));
+            }
+            QRecord provider = merged.getValue("providerId") == null ? null : EmailStore.get(EmailTables.PROVIDER, merged.getValueInteger("providerId"), transaction);
+            if(provider == null)
+            {
+               record.addError(new BadInputStatusMessage("An existing provider is required"));
+            }
+            else if(merged.getValueString("address") != null && record.getErrors().isEmpty())
+            {
+               String domain = provider.getValueString("sendingDomain");
+               String address = merged.getValueString("address");
+               if(domain != null && !domain.isBlank() && !domain.equalsIgnoreCase(address.substring(address.lastIndexOf('@') + 1)))
+               {
+                  record.addError(new BadInputStatusMessage("Sender address domain must match the provider sending domain"));
+               }
+            }
+            if(Boolean.TRUE.equals(merged.getValueBoolean("isDefault")) && !Boolean.TRUE.equals(merged.getValueBoolean("enabled")))
+            {
+               record.addError(new BadInputStatusMessage("A default sender address must be enabled"));
+            }
+            if(merged.getValue("providerId") != null)
+            {
+               providerIds.add(merged.getValue("providerId"));
+            }
+            resulting.add(merged);
+         }
+         if(!providerIds.isEmpty())
+         {
+            List<QRecord> existing = SystemWrites.query(EmailTables.SENDER, new QQueryFilter(new QFilterCriteria("providerId", QCriteriaOperator.IN, new ArrayList<>(providerIds))), transaction);
+            existing.removeIf(r -> records.stream().anyMatch(n -> Objects.equals(n.getValue("id"), r.getValue("id"))));
+            for(int i = 0; i < records.size(); i++)
+            {
+               QRecord merged = resulting.get(i);
+               List<QRecord> peers = new ArrayList<>(existing);
+               for(int j = 0; j < resulting.size(); j++)
+               {
+                  if(j != i)
+                  {
+                     peers.add(resulting.get(j));
+                  }
+               }
+               peers.removeIf(r -> !Objects.equals(r.getValue("providerId"), merged.getValue("providerId")));
+               if(peers.stream().anyMatch(r -> Objects.equals(r.getValueString("address"), merged.getValueString("address"))))
+               {
+                  records.get(i).addError(new BadInputStatusMessage("That sender address already exists for this provider"));
+               }
+               if(Boolean.TRUE.equals(merged.getValueBoolean("isDefault")) && peers.stream().anyMatch(r -> Boolean.TRUE.equals(r.getValueBoolean("isDefault"))))
+               {
+                  records.get(i).addError(new BadInputStatusMessage("Only one sender address per provider can be the default"));
+               }
+            }
+         }
+         return (records);
+      }
+   }
+
    /*******************************************************************************
     ** Canonical addresses and administrator protection for complaint removal.
     *******************************************************************************/
@@ -308,6 +474,27 @@ public final class EmailTableCustomizers
       @Override
       public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records)
       {
+         if(!SystemWrites.active())
+         {
+            for(QRecord row : records)
+            {
+               for(String field : List.of("subject", "htmlBody", "textBody"))
+               {
+                  String value = row.getValueString(field);
+                  if(value != null && value.startsWith("enc:v1:"))
+                  {
+                     row.setValue(field, "[encrypted]");
+                     row.setDisplayValue(field, "[encrypted]");
+                  }
+               }
+            }
+         }
+         for(QRecord row : records)
+         {
+            String subject = row.getValueString("subject");
+            boolean secure = Boolean.TRUE.equals(row.getValueBoolean("phiApproved")) || "[encrypted]".equals(subject) || (subject != null && subject.startsWith("enc:v1:"));
+            row.setRecordLabel(secure ? "Secure message" : subject == null || subject.isBlank() ? "Message " + row.getValue("id") : subject);
+         }
          if(input.getShouldGenerateDisplayValues())
          {
             for(QRecord row : records)

src/main/java/com/kingsrook/qbits/email/metadata/EmailTables.java

@@ -26,6 +26,7 @@ import java.util.List;
 import com.kingsrook.qbits.email.EmailQBitConfig;
 import com.kingsrook.qbits.email.outbox.EmailCategory;
 import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
+import com.kingsrook.qbits.email.support.EmailStore;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.ChildRecordListRenderer;
 import com.kingsrook.qqq.backend.core.instances.QInstanceEnricher;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
@@ -53,15 +54,18 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
 public final class EmailTables
 {
    public static final String PROVIDER = "email_provider";
+   public static final String SENDER = "email_provider_sender_address";
    public static final String MESSAGE = "email_message";
    public static final String ATTEMPT = "email_message_attempt";
    public static final String TEMPLATE = "email_template";
    public static final String VERSION = "email_template_version";
    public static final String BRAND = "email_brand";
    public static final String SUPPRESSION = "email_suppression";
-   public static final List<String> ALL = List.of(PROVIDER, MESSAGE, ATTEMPT, TEMPLATE, VERSION, BRAND, SUPPRESSION);
+   public static final String INBOX = "email_webhook_inbox";
+   public static final String EVENT = "email_event";
+   public static final List<String> ALL = List.of(PROVIDER, SENDER, MESSAGE, ATTEMPT, TEMPLATE, VERSION, BRAND, SUPPRESSION, INBOX, EVENT);
    public static final List<String> MAIN = List.of(MESSAGE, TEMPLATE, BRAND, SUPPRESSION, PROVIDER);
-   public static final List<String> SYSTEM_WRITTEN = List.of(MESSAGE, ATTEMPT);
+   public static final List<String> SYSTEM_WRITTEN = List.of(MESSAGE, ATTEMPT, INBOX, EVENT);
 
    /*******************************************************************************
     ** Utility class.
@@ -95,23 +99,38 @@ public final class EmailTables
       result.add(QPossibleValueSource.newForEnum("email_suppression_scope", EmailEnums.SuppressionScope.values()));
       result.add(QPossibleValueSource.newForEnum("email_suppression_reason", EmailEnums.SuppressionReason.values()));
       result.add(QPossibleValueSource.newForEnum("email_category", EmailCategory.values()));
+      result.add(QPossibleValueSource.newForEnum("email_inbox_status", EmailEnums.InboxStatus.values()));
+      result.add(QPossibleValueSource.newForEnum("email_event_type", EmailEnums.EventType.values()));
+      result.add(QPossibleValueSource.newForEnum("email_bounce_type", EmailEnums.BounceType.values()));
       ALL.forEach(name -> result.add(QPossibleValueSource.newForTable(name)));
+      for(QPossibleValueSource source : result)
+      {
+         if(List.of(PROVIDER, SENDER, MESSAGE, VERSION).contains(source.getName()))
+         {
+            source.withSearchFields(PROVIDER.equals(source.getName()) ? List.of("label", "name") : SENDER.equals(source.getName()) ? List.of("address", "displayName")
+               : MESSAGE.equals(source.getName()) ? List.of("subject") : List.of("versionNumber", "locale"))
+               .withOrderByField("id");
+         }
+      }
       return (result);
    }
 
    /*******************************************************************************
-    ** The seven phase (a) tables.
+    ** Outbound delivery and tracking tables.
     *******************************************************************************/
    public static List<QTableMetaData> tables(EmailQBitConfig config)
    {
       List<QTableMetaData> tables = new ArrayList<>();
       tables.add(provider(config));
+      tables.add(sender(config));
       tables.add(message(config));
       tables.add(messageattempt(config));
       tables.add(template(config));
       tables.add(templateversion(config));
       tables.add(brand(config));
       tables.add(suppression(config));
+      tables.add(inbox(config));
+      tables.add(event(config));
       for(QTableMetaData table : tables)
       {
          for(QFieldMetaData field : config.getSecurityFields())
@@ -189,13 +208,37 @@ public final class EmailTables
          .withField(field("lastFailureMessage", QFieldType.STRING).withMaxLength(500))
          .withField(field("dispatchLock", QFieldType.INTEGER).withDefaultValue(0).withIsHidden(true).withIsEditable(false))
          .withField(field("defaultSlot", QFieldType.INTEGER).withIsHidden(true).withIsEditable(false));
-      table.withRecordLabelFormatAndFields("%s", "name");
+      table.withRecordLabelFormat(null).withRecordLabelFields(List.of());
       table.withUniqueKey(new UniqueKey("name"));
       table.withUniqueKey(new UniqueKey("defaultSlot"));
       table.withSection(SectionFactory.defaultT1("id", "name", "label", "kind", "enabled", "isDefault"));
       table.withSection(SectionFactory.defaultT2("fromAddress", "fromName", "replyTo", "sendingDomain", "host", "port", "security", "region", "usernameEnvName", "secretEnvName", "webhookSecretEnvName", "snsTopicArn", "configurationSet", "messageStream", "maxPerMinute", "maxPerDay", "trackOpens", "trackClicks", "phiAllowed", "healthStatus", "lastSuccessDate", "lastFailureDate", "lastFailureMessage"));
       table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
+      table.withSection(SectionFactory.customT2("senders", new QIcon("list")).withLabel("Sender Addresses").withWidgetName(SENDER + "_children"));
       table.withSection(SectionFactory.customT2("children", new QIcon("list")).withLabel("Messages").withWidgetName(PROVIDER + "_children"));
+      table.withSection(SectionFactory.customT2("inbox", new QIcon("list")).withLabel("Webhook Inbox").withWidgetName(INBOX + "_children"));
+      return (table);
+   }
+
+
+   /*******************************************************************************
+    ** Metadata for email_provider_sender_address. The provider list in the
+    ** nav is the only entry point; rows are managed as a child list on the provider.
+    *******************************************************************************/
+   private static QTableMetaData sender(EmailQBitConfig config)
+   {
+      QTableMetaData table = base(config, SENDER, "Provider Sender Address")
+         .withField(field("providerId", QFieldType.INTEGER).withPossibleValueSourceName(PROVIDER).withIsRequired(true))
+         .withField(field("address", QFieldType.STRING).withIsRequired(true).withMaxLength(500))
+         .withField(field("displayName", QFieldType.STRING).withMaxLength(500))
+         .withField(field("isDefault", QFieldType.BOOLEAN).withDefaultValue(false))
+         .withField(field("enabled", QFieldType.BOOLEAN).withDefaultValue(true))
+         .withField(field("note", QFieldType.TEXT));
+      table.withRecordLabelFormat(null).withRecordLabelFields(List.of());
+      table.withUniqueKey(new UniqueKey("providerId", "address"));
+      table.withSection(SectionFactory.defaultT1("id", "providerId", "address", "displayName", "isDefault", "enabled"));
+      table.withSection(SectionFactory.defaultT2("note"));
+      table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
       return (table);
    }
 
@@ -211,18 +254,22 @@ public final class EmailTables
          .withField(field("ccAddresses", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("bccAddresses", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("fromAddress", QFieldType.STRING).withIsSensitive(true).withMaxLength(500))
+         .withField(field("fromAddressId", QFieldType.INTEGER).withPossibleValueSourceName(SENDER).withPossibleValueSourceFilter(EmailStore.equal("providerId", "${input.providerId}")))
          .withField(field("replyTo", QFieldType.STRING).withIsSensitive(true).withMaxLength(500))
          .withField(field("subject", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("templateId", QFieldType.INTEGER).withPossibleValueSourceName(TEMPLATE))
-         .withField(field("templateVersionId", QFieldType.INTEGER).withPossibleValueSourceName(VERSION))
+         .withField(field("templateVersionId", QFieldType.INTEGER).withPossibleValueSourceName(VERSION).withPossibleValueSourceFilter(EmailStore.equal("templateId", "${input.templateId}")))
          .withField(field("brandId", QFieldType.INTEGER).withPossibleValueSourceName(BRAND))
          .withField(field("category", QFieldType.STRING).withPossibleValueSourceName("email_category").withMaxLength(500))
          .withField(field("locale", QFieldType.STRING).withDefaultValue("en").withMaxLength(500))
          .withField(field("variablesSnapshot", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("htmlBody", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("textBody", QFieldType.TEXT).withIsSensitive(true))
+         .withField(field("phiApproved", QFieldType.BOOLEAN).withDefaultValue(false).withIsEditable(false))
+         .withField(field("unsubscribeUrl", QFieldType.TEXT))
          .withField(field("bodySha256", QFieldType.STRING).withMaxLength(500))
          .withField(field("idempotencyKey", QFieldType.STRING).withMaxLength(500))
+         .withField(field("rfcMessageId", QFieldType.STRING).withMaxLength(500))
          .withField(field("providerId", QFieldType.INTEGER).withPossibleValueSourceName(PROVIDER))
          .withField(field("providerMessageId", QFieldType.STRING).withMaxLength(500))
          .withField(field("attemptCount", QFieldType.INTEGER).withDefaultValue(0))
@@ -232,6 +279,8 @@ public final class EmailTables
          .withField(field("finishedDate", QFieldType.DATE_TIME))
          .withField(field("sentDate", QFieldType.DATE_TIME))
          .withField(field("deliveredDate", QFieldType.DATE_TIME))
+         .withField(field("bouncedDate", QFieldType.DATE_TIME))
+         .withField(field("complainedDate", QFieldType.DATE_TIME))
          .withField(field("deadLetterDate", QFieldType.DATE_TIME))
          .withField(field("linkedTableName", QFieldType.STRING).withMaxLength(500))
          .withField(field("linkedRecordId", QFieldType.STRING).withMaxLength(500)
@@ -240,11 +289,15 @@ public final class EmailTables
          .withField(field("senderProcess", QFieldType.STRING).withMaxLength(500))
          .withField(field("suppressedAddresses", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("sendAfter", QFieldType.DATE_TIME));
+      table.withRecordLabelFormat(null).withRecordLabelFields(List.of());
+      table.getField("subject").setIsHeavy(false);
       table.withUniqueKey(new UniqueKey("idempotencyKey"));
+      table.withUniqueKey(new UniqueKey("rfcMessageId"));
       table.withSection(SectionFactory.defaultT1("id", "status", "toAddresses", "ccAddresses", "bccAddresses", "fromAddress"));
-      table.withSection(SectionFactory.defaultT2("replyTo", "subject", "templateId", "templateVersionId", "brandId", "category", "locale", "variablesSnapshot", "htmlBody", "textBody", "bodySha256", "idempotencyKey", "providerId", "providerMessageId", "attemptCount", "nextAttemptDate", "leaseExpiresDate", "lastError", "finishedDate", "sentDate", "deliveredDate", "deadLetterDate", "linkedTableName", "linkedRecordId", "senderQbit", "senderProcess", "suppressedAddresses", "sendAfter"));
+      table.withSection(SectionFactory.defaultT2("fromAddressId", "replyTo", "subject", "templateId", "templateVersionId", "brandId", "category", "locale", "variablesSnapshot", "htmlBody", "textBody", "phiApproved", "unsubscribeUrl", "bodySha256", "idempotencyKey", "rfcMessageId", "providerId", "providerMessageId", "attemptCount", "nextAttemptDate", "leaseExpiresDate", "lastError", "finishedDate", "sentDate", "deliveredDate", "bouncedDate", "complainedDate", "deadLetterDate", "linkedTableName", "linkedRecordId", "senderQbit", "senderProcess", "suppressedAddresses", "sendAfter"));
       table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
       table.withSection(SectionFactory.customT2("children", new QIcon("list")).withLabel("Attempts").withWidgetName(MESSAGE + "_children"));
+      table.withSection(SectionFactory.customT2("events", new QIcon("list")).withLabel("Events").withWidgetName(EVENT + "_children"));
       return (table);
    }
 
@@ -255,7 +308,7 @@ public final class EmailTables
    private static QTableMetaData messageattempt(EmailQBitConfig config)
    {
       QTableMetaData table = base(config, ATTEMPT, "Message Attempt")
-         .withField(field("messageId", QFieldType.INTEGER).withPossibleValueSourceName(MESSAGE).withIsRequired(true))
+         .withField(field("messageId", QFieldType.INTEGER).withPossibleValueSourceName(MESSAGE).withIsRequired(true).withPossibleValueSourceFilter(EmailStore.equal("providerId", "${input.providerId}")))
          .withField(field("attemptNumber", QFieldType.INTEGER).withIsRequired(true))
          .withField(field("outcome", QFieldType.STRING).withPossibleValueSourceName("email_attempt_outcome").withMaxLength(500))
          .withField(field("providerId", QFieldType.INTEGER).withPossibleValueSourceName(PROVIDER))
@@ -284,17 +337,20 @@ public final class EmailTables
          .withField(field("category", QFieldType.STRING).withPossibleValueSourceName("email_category").withMaxLength(500))
          .withField(field("kind", QFieldType.STRING).withPossibleValueSourceName("email_template_kind").withIsRequired(true).withMaxLength(500))
          .withField(field("brandId", QFieldType.INTEGER).withPossibleValueSourceName(BRAND))
-         .withField(field("activeVersionId", QFieldType.INTEGER).withPossibleValueSourceName(VERSION))
-         .withField(field("phiApproved", QFieldType.BOOLEAN).withDefaultValue(false))
-         .withField(field("phiApprovedBy", QFieldType.STRING).withMaxLength(500))
-         .withField(field("phiApprovedDate", QFieldType.DATE_TIME))
+         .withField(field("activeVersionId", QFieldType.INTEGER).withPossibleValueSourceName(VERSION).withIsEditable(false).withPossibleValueSourceFilter(EmailStore.equal("templateId", "${input.id}")))
+         .withField(field("approvedVersionId", QFieldType.INTEGER).withIsEditable(false).withPossibleValueSourceName(VERSION).withPossibleValueSourceFilter(EmailStore.equal("templateId", "${input.id}")))
+         .withField(field("versionLock", QFieldType.INTEGER).withIsHidden(true).withIsEditable(false))
+         .withField(field("phiApproved", QFieldType.BOOLEAN).withDefaultValue(false).withIsEditable(false))
+         .withField(field("phiApprovedBy", QFieldType.STRING).withMaxLength(500).withIsEditable(false))
+         .withField(field("phiApprovedDate", QFieldType.DATE_TIME).withIsEditable(false))
          .withField(field("editPermissionName", QFieldType.STRING).withMaxLength(500))
-         .withField(field("ownerQbit", QFieldType.STRING).withMaxLength(500))
+         .withField(field("ownerQbit", QFieldType.STRING).withMaxLength(500).withIsEditable(false)
+            .withHelpContent(new com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent("Set by the qbit that registered the template. Messages sent from it name that qbit as their sender unless the sender says otherwise.")))
          .withField(field("description", QFieldType.TEXT));
       table.withRecordLabelFormatAndFields("%s", "name");
       table.withUniqueKey(new UniqueKey("name"));
       table.withSection(SectionFactory.defaultT1("id", "name", "label", "category", "kind", "brandId"));
-      table.withSection(SectionFactory.defaultT2("activeVersionId", "phiApproved", "phiApprovedBy", "phiApprovedDate", "editPermissionName", "ownerQbit", "description"));
+      table.withSection(SectionFactory.defaultT2("activeVersionId", "approvedVersionId", "phiApproved", "phiApprovedBy", "phiApprovedDate", "editPermissionName", "ownerQbit", "description"));
       table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
       table.withSection(SectionFactory.customT2("children", new QIcon("list")).withLabel("Versions").withWidgetName(TEMPLATE + "_children"));
       return (table);
@@ -307,20 +363,22 @@ public final class EmailTables
    private static QTableMetaData templateversion(EmailQBitConfig config)
    {
       QTableMetaData table = base(config, VERSION, "Template Version")
-         .withField(field("templateId", QFieldType.INTEGER).withPossibleValueSourceName(TEMPLATE))
-         .withField(field("versionNumber", QFieldType.INTEGER))
-         .withField(field("status", QFieldType.STRING).withPossibleValueSourceName("email_version_status").withMaxLength(500))
-         .withField(field("locale", QFieldType.STRING).withDefaultValue("en").withMaxLength(500))
+         .withField(field("templateId", QFieldType.INTEGER).withPossibleValueSourceName(TEMPLATE).withIsRequired(true))
+         .withField(field("versionNumber", QFieldType.INTEGER).withIsRequired(true))
+         .withField(field("status", QFieldType.STRING).withPossibleValueSourceName("email_version_status").withDefaultValue("DRAFT").withIsEditable(false).withMaxLength(500))
+         .withField(field("locale", QFieldType.STRING).withDefaultValue("en").withMaxLength(500).withIsRequired(true))
          .withField(field("subject", QFieldType.TEXT).withIsSensitive(true))
          .withField(field("preheader", QFieldType.TEXT))
          .withField(field("bodySource", QFieldType.TEXT))
          .withField(field("textSource", QFieldType.TEXT))
-         .withField(field("compiledHtml", QFieldType.TEXT))
+         .withField(field("compiledHtml", QFieldType.TEXT).withIsEditable(false))
          .withField(field("variablesSchema", QFieldType.TEXT))
          .withField(field("sampleVariables", QFieldType.TEXT))
          .withField(field("createdBy", QFieldType.STRING).withMaxLength(500))
          .withField(field("activatedDate", QFieldType.DATE_TIME));
+      table.withRecordLabelFormat(null).withRecordLabelFields(List.of());
       table.withUniqueKey(new UniqueKey("templateId", "versionNumber", "locale"));
+      table.withSection(SectionFactory.customT2("preview", new QIcon("preview")).withLabel("Preview").withWidgetName("emailTemplatePreview"));
       table.withSection(SectionFactory.defaultT1("id", "templateId", "versionNumber", "status", "locale", "subject"));
       table.withSection(SectionFactory.defaultT2("preheader", "bodySource", "textSource", "compiledHtml", "variablesSchema", "sampleVariables", "createdBy", "activatedDate"));
       table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
@@ -343,6 +401,8 @@ public final class EmailTables
          .withField(field("textColor", QFieldType.STRING).withMaxLength(500))
          .withField(field("backgroundColor", QFieldType.STRING).withMaxLength(500))
          .withField(field("darkBackgroundColor", QFieldType.STRING).withMaxLength(500))
+         .withField(field("darkPrimaryColor", QFieldType.STRING).withMaxLength(500))
+         .withField(field("darkButtonTextColor", QFieldType.STRING).withMaxLength(500))
          .withField(field("darkTextColor", QFieldType.STRING).withMaxLength(500))
          .withField(field("buttonTextColor", QFieldType.STRING).withMaxLength(500))
          .withField(field("footerMarkdown", QFieldType.TEXT))
@@ -354,7 +414,7 @@ public final class EmailTables
       table.withRecordLabelFormatAndFields("%s", "name");
       table.withUniqueKey(new UniqueKey("name"));
       table.withSection(SectionFactory.defaultT1("id", "name", "label", "logoUrl", "logoDarkUrl", "logoAlt"));
-      table.withSection(SectionFactory.defaultT2("primaryColor", "textColor", "backgroundColor", "darkBackgroundColor", "darkTextColor", "buttonTextColor", "footerMarkdown", "postalAddress", "socialLinks", "siteUrl", "isDefault", "appName"));
+      table.withSection(SectionFactory.defaultT2("primaryColor", "textColor", "backgroundColor", "darkBackgroundColor", "darkTextColor", "darkPrimaryColor", "darkButtonTextColor", "buttonTextColor", "footerMarkdown", "postalAddress", "socialLinks", "siteUrl", "isDefault", "appName"));
       table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
       return (table);
    }
@@ -370,7 +430,7 @@ public final class EmailTables
          .withField(field("scope", QFieldType.STRING).withPossibleValueSourceName("email_suppression_scope").withIsRequired(true).withMaxLength(500))
          .withField(field("reason", QFieldType.STRING).withPossibleValueSourceName("email_suppression_reason").withIsRequired(true).withMaxLength(500))
          .withField(field("sourceMessageId", QFieldType.INTEGER))
-         .withField(field("sourceEventId", QFieldType.INTEGER))
+         .withField(field("sourceEventId", QFieldType.INTEGER).withPossibleValueSourceName(EVENT).withPossibleValueSourceFilter(EmailStore.equal("messageId", "${input.sourceMessageId}")))
          .withField(field("note", QFieldType.TEXT))
          .withField(field("createdDate", QFieldType.DATE_TIME))
          .withField(field("expiresDate", QFieldType.DATE_TIME));
@@ -381,12 +441,59 @@ public final class EmailTables
       return (table);
    }
 
+
+   /*******************************************************************************
+    ** System-written webhook inbox records.
+    *******************************************************************************/
+   private static QTableMetaData inbox(EmailQBitConfig config)
+   {
+      QTableMetaData table = base(config, INBOX, "Webhook Inbox")
+         .withField(field("providerId", QFieldType.INTEGER).withIsRequired(true).withPossibleValueSourceName(PROVIDER))
+         .withField(field("kind", QFieldType.STRING).withMaxLength(500))
+         .withField(field("externalEventId", QFieldType.STRING).withMaxLength(500).withIsRequired(true))
+         .withField(field("nonce", QFieldType.STRING).withMaxLength(500))
+         .withField(field("status", QFieldType.STRING).withMaxLength(500).withIsRequired(true).withPossibleValueSourceName("email_inbox_status"))
+         .withField(field("attempts", QFieldType.INTEGER))
+         .withField(field("nextAttemptDate", QFieldType.DATE_TIME))
+         .withField(field("lastError", QFieldType.STRING).withMaxLength(500))
+         .withField(field("payloadJson", QFieldType.TEXT).withIsSensitive(true))
+         .withField(field("payloadSha256", QFieldType.STRING).withMaxLength(500))
+         .withField(field("receivedDate", QFieldType.DATE_TIME))
+         .withField(field("processedDate", QFieldType.DATE_TIME));
+      table.withUniqueKey(new UniqueKey("providerId", "externalEventId"));
+      table.withUniqueKey(new UniqueKey("providerId", "nonce"));
+      table.withSection(SectionFactory.defaultT1("id", "providerId", "kind", "externalEventId", "nonce", "status", "attempts", "nextAttemptDate", "lastError", "payloadJson", "payloadSha256", "receivedDate", "processedDate"));
+      table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
+      return (table);
+   }
+
+   /*******************************************************************************
+    ** System-written event records.
+    *******************************************************************************/
+   private static QTableMetaData event(EmailQBitConfig config)
+   {
+      QTableMetaData table = base(config, EVENT, "Event")
+         .withField(field("messageId", QFieldType.INTEGER).withIsRequired(true).withPossibleValueSourceName(MESSAGE).withPossibleValueSourceFilter(EmailStore.equal("providerId", "${input.providerId}")))
+         .withField(field("providerId", QFieldType.INTEGER).withPossibleValueSourceName(PROVIDER))
+         .withField(field("eventType", QFieldType.STRING).withMaxLength(500).withIsRequired(true).withPossibleValueSourceName("email_event_type"))
+         .withField(field("bounceType", QFieldType.STRING).withMaxLength(500).withPossibleValueSourceName("email_bounce_type"))
+         .withField(field("recipient", QFieldType.STRING).withMaxLength(500).withIsSensitive(true))
+         .withField(field("occurredDate", QFieldType.DATE_TIME))
+         .withField(field("detail", QFieldType.STRING).withMaxLength(500))
+         .withField(field("url", QFieldType.TEXT).withIsSensitive(true))
+         .withField(field("eventKey", QFieldType.STRING).withMaxLength(500).withIsRequired(true).withIsHidden(true));
+      table.withUniqueKey(new UniqueKey("eventKey"));
+      table.withSection(SectionFactory.defaultT1("id", "messageId", "providerId", "eventType", "bounceType", "recipient", "occurredDate", "detail", "url"));
+      table.withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
+      return (table);
+   }
+
    /*******************************************************************************
     ** Relations used by child lists.
     *******************************************************************************/
    public static List<QJoinMetaData> joins()
    {
-      return (List.of(join(PROVIDER, MESSAGE, "providerId"), join(MESSAGE, ATTEMPT, "messageId"), join(TEMPLATE, VERSION, "templateId")));
+      return (List.of(join(PROVIDER, MESSAGE, "providerId"), join(MESSAGE, ATTEMPT, "messageId"), join(TEMPLATE, VERSION, "templateId"), join(PROVIDER, INBOX, "providerId"), join(PROVIDER, SENDER, "providerId"), join(MESSAGE, EVENT, "messageId")));
    }
 
    /*******************************************************************************
@@ -406,8 +513,8 @@ public final class EmailTables
       List<QWidgetMetaData> widgets = new ArrayList<>();
       for(QJoinMetaData join : joins())
       {
-         widgets.add(ChildRecordListRenderer.widgetMetaDataBuilder(join).withName(join.getLeftTable() + "_children")
-            .withLabel(join.getRightTable().equals(ATTEMPT) ? "Attempts" : join.getRightTable().equals(VERSION) ? "Versions" : "Messages")
+         widgets.add(ChildRecordListRenderer.widgetMetaDataBuilder(join).withName(List.of(INBOX, EVENT, SENDER).contains(join.getRightTable()) ? join.getRightTable() + "_children" : join.getLeftTable() + "_children")
+            .withLabel(join.getRightTable().equals(INBOX) ? "Webhook Inbox" : join.getRightTable().equals(SENDER) ? "Sender Addresses" : join.getRightTable().equals(EVENT) ? "Events" : join.getRightTable().equals(ATTEMPT) ? "Attempts" : join.getRightTable().equals(VERSION) ? "Versions" : "Messages")
             .withMaxRows(50).getWidgetMetaData().withGridColumns(12).withPermissionRules(permissionRules()));
       }
       return (widgets);

src/main/java/com/kingsrook/qbits/email/outbox/AdHocEmailRenderer.java

@@ -21,15 +21,10 @@
 package com.kingsrook.qbits.email.outbox;
 
 
-import java.util.List;
-import org.commonmark.ext.autolink.AutolinkExtension;
-import org.commonmark.ext.gfm.tables.TablesExtension;
-import org.commonmark.parser.Parser;
-import org.commonmark.renderer.html.HtmlRenderer;
 
 
 /*******************************************************************************
- ** Minimal part 1 layout. Markdown raw HTML and unsafe URL schemes are disabled.
+ ** Branded ad-hoc rendering. Markdown raw HTML and unsafe URL schemes are disabled.
  *******************************************************************************/
 public class AdHocEmailRenderer implements EmailRenderer
 {
@@ -39,36 +34,22 @@ public class AdHocEmailRenderer implements EmailRenderer
    @Override
    public Rendered render(EmailRequest request)
    {
-      String html = request.getHtmlBody();
-      if(html == null)
+      try
       {
-         if(request.getMarkdownBody() != null)
+         var brand = com.kingsrook.qbits.email.render.EmailBrands.resolve(request.getBrandName(), null);
+         String html = request.getHtmlBody();
+         if(html == null)
          {
-            var extensions = List.of(TablesExtension.create(), AutolinkExtension.create());
-            html = HtmlRenderer.builder().escapeHtml(true).sanitizeUrls(true).extensions(extensions).build()
-               .render(Parser.builder().extensions(extensions).build().parse(request.getMarkdownBody()));
-         }
-         else
-         {
-            html = "<pre>" + escape(request.getTextBody()) + "</pre>";
+            String body = request.getMarkdownBody() == null ? "<pre>" + com.kingsrook.qbits.email.template.EmailTemplateEngine.escape(request.getTextBody()) + "</pre>"
+               : com.kingsrook.qbits.email.render.EmailMarkdown.render(request.getMarkdownBody(), brand);
+            html = com.kingsrook.qbits.email.render.EmailLayout.render(body, "", brand,
+               request.getCategory() == null ? EmailCategory.TRANSACTIONAL : request.getCategory(), "");
          }
+         return (new Rendered(html, request.getTextBody() == null ? com.kingsrook.qbits.email.render.HtmlToText.convert(html) : request.getTextBody()));
       }
-      String text = request.getTextBody();
-      if(text == null)
+      catch(com.kingsrook.qqq.backend.core.exceptions.QException e)
       {
-         text = html.replaceAll("(?is)<(script|style)[^>]*>.*?</\\1>", "")
-            .replaceAll("(?i)<br\\s*/?>|</(p|div|li|h[1-6]|tr)>", "\n")
-            .replaceAll("<[^>]+>", "").replace("&lt;", "<").replace("&gt;", ">").replace("&quot;", "\"")
-            .replace("&#39;", "'").replace("&nbsp;", " ").replace("&amp;", "&").strip();
+         throw (new IllegalArgumentException("Email brand is unavailable"));
       }
-      return (new Rendered("<!doctype html><html><body><main>" + html + "</main></body></html>", text));
-   }
-
-   /*******************************************************************************
-    ** Escape plain text for the fallback HTML part.
-    *******************************************************************************/
-   private static String escape(String text)
-   {
-      return (text == null ? "" : text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;"));
    }
 }

src/main/java/com/kingsrook/qbits/email/outbox/EmailEffectOutcome.java

@@ -0,0 +1,33 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.outbox;
+
+
+/*******************************************************************************
+ ** Internal; use EmailApi.
+ ** Durable handoff outcomes. Operational failures propagate to the caller.
+ *******************************************************************************/
+@Deprecated(forRemoval = false)
+public enum EmailEffectOutcome
+{
+   QUEUED_OR_DUPLICATE,
+   REFUSED
+}

src/main/java/com/kingsrook/qbits/email/outbox/EmailEffects.java

@@ -0,0 +1,124 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.outbox;
+
+
+import java.util.List;
+import java.util.Optional;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Internal; use EmailApi.
+ ** Outbox handoff and system-read reconciliation for trusted effect dispatchers.
+ ** This API has no dependency on core durable-job types. Sending retains the
+ ** EmailService permission checks; callers must supply a request without a transaction.
+ *******************************************************************************/
+@Deprecated(forRemoval = false)
+public final class EmailEffects
+{
+   /*******************************************************************************
+    ** A refusal can have a reference when suppression retained an audit row.
+    *******************************************************************************/
+   public record Result(EmailEffectOutcome outcome, EmailMessageRef message, List<String> reasons)
+   {
+      /*******************************************************************************
+       ** Preserve the original constructor for callers that only need the reference.
+       *******************************************************************************/
+      public Result(EmailEffectOutcome outcome, EmailMessageRef message)
+      {
+         this(outcome, message, List.of());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailEffects()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Hand off once with the effect's identity. Refuse invalid or conflicting keys
+    ** and caller transactions: success must mean the outbox has committed already.
+    ** Database failures throw QException and must not become a permanent refusal.
+    *******************************************************************************/
+   public static Result send(EmailRequest request, String effectIdempotencyKey) throws QException
+   {
+      if(request == null || effectIdempotencyKey == null || effectIdempotencyKey.isBlank() || effectIdempotencyKey.length() > 500
+         || request.getTransaction() != null
+         || request.getIdempotencyKey() != null && !request.getIdempotencyKey().equals(effectIdempotencyKey))
+      {
+         return (new Result(EmailEffectOutcome.REFUSED, null, List.of("An email request without a caller transaction and a valid, matching effect key are required")));
+      }
+      request.withIdempotencyKey(effectIdempotencyKey);
+      EmailSendResult result = EmailService.send(request);
+      EmailMessageRef message = result.messageId() == null ? null : find("id", result.messageId()).orElseThrow(() -> new QException("Queued email reference is unavailable"));
+      boolean refused = result.status() == EmailSendResult.Status.REFUSED || result.status() == EmailSendResult.Status.SUPPRESSED
+         || message != null && "SUPPRESSED".equals(message.status());
+      List<String> reasons = message != null && "SUPPRESSED".equals(message.status()) ? List.of("All recipients are suppressed") : result.reasons();
+      return (new Result(refused ? EmailEffectOutcome.REFUSED : EmailEffectOutcome.QUEUED_OR_DUPLICATE, message, reasons));
+   }
+
+
+
+   /*******************************************************************************
+    ** Look up a committed outbox row by its exact effect or application key.
+    *******************************************************************************/
+   public static Optional<EmailMessageRef> findByIdempotencyKey(String key) throws QException
+   {
+      return (key == null || key.isBlank() ? Optional.empty() : find("idempotencyKey", key));
+   }
+
+
+
+   /*******************************************************************************
+    ** Look up the exact bracketed RFC Message-ID stored at enqueue time.
+    *******************************************************************************/
+   public static Optional<EmailMessageRef> findByRfcMessageId(String messageId) throws QException
+   {
+      return (messageId == null || messageId.isBlank() ? Optional.empty() : find("rfcMessageId", messageId));
+   }
+
+
+
+   /*******************************************************************************
+    ** Use the same authorized read scope as the dispatcher; expose only references.
+    *******************************************************************************/
+   private static Optional<EmailMessageRef> find(String field, java.io.Serializable value) throws QException
+   {
+      List<QRecord> rows = SystemWrites.query(EmailTables.MESSAGE, EmailStore.equal(field, value).withLimit(1));
+      if(rows.isEmpty())
+      {
+         return (Optional.empty());
+      }
+      QRecord row = rows.getFirst();
+      return (Optional.of(new EmailMessageRef(row.getValueInteger("id"), row.getValueString("status"), row.getValueString("rfcMessageId"), row.getValueString("providerMessageId"))));
+   }
+}

src/main/java/com/kingsrook/qbits/email/outbox/EmailJobEffectTarget.java

@@ -0,0 +1,200 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.outbox;
+
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+import com.kingsrook.qqq.backend.core.context.CapturedContext;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.jobs.DurableJobsMetaData;
+import com.kingsrook.qqq.backend.core.jobs.JobSessions;
+import com.kingsrook.qqq.backend.core.jobs.effects.EffectRequest;
+import com.kingsrook.qqq.backend.core.jobs.effects.EffectResult;
+import com.kingsrook.qqq.backend.core.jobs.effects.EffectTarget;
+import com.kingsrook.qqq.backend.core.jobs.effects.ReconcileResult;
+import com.kingsrook.qqq.backend.core.jobs.store.DurableJobStore;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+
+
+/*******************************************************************************
+ ** Durable jobs target for IDEMPOTENT_EXTERNAL email effects. SENT acknowledges
+ ** the committed email outbox, whose key deduplication makes retries safe. The
+ ** email dispatcher owns provider delivery and preserves the stored Message-ID.
+ ** Payload keys and types are documented in docs/DURABLE-JOBS.md.
+ *******************************************************************************/
+public class EmailJobEffectTarget implements EffectTarget
+{
+   public static final String TARGET_NAME = "email";
+
+
+
+   /*******************************************************************************
+    ** Register after enabling durable jobs; leave instances without jobs alone.
+    *******************************************************************************/
+   public static void register(QInstance instance)
+   {
+      DurableJobsMetaData jobs = DurableJobsMetaData.of(instance);
+      if(jobs != null)
+      {
+         jobs.withEffectTarget(TARGET_NAME, new QCodeReference(EmailJobEffectTarget.class));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Enqueue under the job owner's current permissions and captured scope.
+    ** Other exceptions are uncertain; core may safely resend using the same key.
+    *******************************************************************************/
+   @Override
+   public EffectResult deliver(EffectRequest r)
+   {
+      try
+      {
+         EmailRequest request = decode(r.payload()).withSender("jobs", r.effectName());
+         EmailEffects.Result result;
+         if(r.jobId() == null)
+         {
+            result = EmailEffects.send(request, r.idempotencyKey());
+         }
+         else
+         {
+            QInstance instance = QContext.getQInstance();
+            QSession owner;
+            try
+            {
+               QRecord job = new DurableJobStore(DurableJobsMetaData.of(instance)).getJob(r.jobId());
+               if(job == null)
+               {
+                  return (EffectResult.failed("The job's owner can no longer send it: job not found"));
+               }
+               owner = JobSessions.forJob(instance, job);
+            }
+            catch(QPermissionDeniedException | QAuthenticationException e)
+            {
+               return (EffectResult.failed("The job's owner can no longer send it: owner session unavailable"));
+            }
+            AtomicReference<EmailEffects.Result> handoff = new AtomicReference<>();
+            QContext.withTemporaryContext(new CapturedContext(instance, owner),
+               () -> handoff.set(EmailEffects.send(request, r.idempotencyKey())));
+            result = handoff.get();
+         }
+         if(result.outcome() == EmailEffectOutcome.REFUSED)
+         {
+            return (EffectResult.failed(String.join("; ", result.reasons())));
+         }
+         return (EffectResult.sent(String.valueOf(result.message().id())));
+      }
+      catch(Exception e)
+      {
+         // Exception details can contain payloads or database values.
+         return (EffectResult.unknown("Email handoff could not be confirmed (" + e.getClass().getSimpleName() + ")"));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Reconcile handoff by existence, including suppressed and terminal audit rows.
+    *******************************************************************************/
+   @Override
+   public ReconcileResult reconcile(EffectRequest r) throws QException
+   {
+      return (EmailEffects.findByIdempotencyKey(r.idempotencyKey())
+         .map(message -> ReconcileResult.found(String.valueOf(message.id())))
+         .orElseGet(ReconcileResult::notFound));
+   }
+
+
+
+   /*******************************************************************************
+    ** Decode only supported values; identity, sender and transaction cannot be
+    ** overridden by payload keys. Variables retain normal template/PHI validation.
+    *******************************************************************************/
+   static EmailRequest decode(Map<String, Serializable> payload)
+   {
+      Map<String, Serializable> values = payload == null ? Map.of() : payload;
+      EmailRequest request = new EmailRequest()
+         .withTo(addresses(values.get("to")))
+         .withCc(addresses(values.get("cc")))
+         .withBcc(addresses(values.get("bcc")))
+         .withFrom((String) values.get("from"))
+         .withFromAddressId((Integer) values.get("fromAddressId"))
+         .withReplyTo((String) values.get("replyTo"))
+         .withSubject((String) values.get("subject"))
+         .withTemplateName((String) values.get("templateName"))
+         .withMarkdownBody((String) values.get("markdownBody"))
+         .withHtmlBody((String) values.get("htmlBody"))
+         .withTextBody((String) values.get("textBody"))
+         .withProviderName((String) values.get("providerName"))
+         .withBrandName((String) values.get("brandName"))
+         .withLinkedRecord((String) values.get("linkedTableName"), values.get("linkedRecordId"));
+      if(values.get("locale") != null)
+      {
+         request.withLocale((String) values.get("locale"));
+      }
+      if(values.get("category") != null)
+      {
+         request.withCategory(EmailCategory.valueOf((String) values.get("category")));
+      }
+      if(values.get("sendAfter") != null)
+      {
+         request.withSendAfter(Instant.parse((String) values.get("sendAfter")));
+      }
+      if(values.get("variables") instanceof Map<?, ?> variables)
+      {
+         variables.forEach((key, value) -> request.withVariable((String) key, (Serializable) value));
+      }
+      else if(values.get("variables") != null)
+      {
+         throw (new IllegalArgumentException("variables must be a map"));
+      }
+      return (request);
+   }
+
+
+
+   /*******************************************************************************
+    ** Accept one mailbox or a list of mailboxes, without comma splitting.
+    *******************************************************************************/
+   private static List<String> addresses(Object value)
+   {
+      if(value == null)
+      {
+         return (List.of());
+      }
+      if(value instanceof String address)
+      {
+         return (List.of(address));
+      }
+      return (((List<?>) value).stream().map(String.class::cast).toList());
+   }
+}

src/main/java/com/kingsrook/qbits/email/outbox/EmailMessageRef.java

@@ -0,0 +1,31 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.outbox;
+
+
+/*******************************************************************************
+ ** Internal; use EmailApi.
+ ** Reconciliation reference without message bodies, recipients or credentials.
+ *******************************************************************************/
+@Deprecated(forRemoval = false)
+public record EmailMessageRef(Integer id, String status, String rfcMessageId, String providerMessageId)
+{
+}

src/main/java/com/kingsrook/qbits/email/outbox/EmailRequest.java

@@ -31,7 +31,7 @@ import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 
 
 /*******************************************************************************
- ** Synchronous enqueue request. Templates and classified variables arrive in part 2.
+ ** Synchronous enqueue request with explicit record provenance.
  *******************************************************************************/
 public class EmailRequest
 {
@@ -39,6 +39,7 @@ public class EmailRequest
    private List<String> cc = new ArrayList<>();
    private List<String> bcc = new ArrayList<>();
    private String from;
+   private Integer fromAddressId;
    private String replyTo;
    private String subject;
    private String markdownBody;
@@ -48,7 +49,7 @@ public class EmailRequest
    private String templateName;
    private String brandName;
    private String locale = "en";
-   private EmailCategory category = EmailCategory.TRANSACTIONAL;
+   private EmailCategory category;
    private String idempotencyKey;
    private Instant sendAfter;
    private String linkedTableName;
@@ -57,6 +58,7 @@ public class EmailRequest
    private String senderProcess;
    private QBackendTransaction transaction;
    private String transactionBackendName;
+   private Map<String, RecordVariable> recordVariables = new LinkedHashMap<>();
    private Map<String, Serializable> variables = new LinkedHashMap<>();
    private Map<String, Serializable> securityValues = new LinkedHashMap<>();
 
@@ -118,7 +120,7 @@ public class EmailRequest
    }
 
    /*******************************************************************************
-    ** Accept template variables as a seam; part 1 refuses variable-bearing requests.
+    ** Bind one schema variable.
     *******************************************************************************/
    public EmailRequest withVariable(String name, Serializable value)
    {
@@ -131,7 +133,7 @@ public class EmailRequest
     *******************************************************************************/
    public EmailRequest withRecordVariable(String name, String table, Serializable id)
    {
-      variables.put(name, new LinkedHashMap<>(Map.of("table", table, "id", id)));
+      recordVariables.put(name, new RecordVariable(table, id));
       return (this);
    }
 
@@ -212,6 +214,26 @@ public class EmailRequest
    }
 
 
+   /*******************************************************************************
+    ** Getter for fromAddressId.
+    *******************************************************************************/
+   public Integer getFromAddressId()
+   {
+      return (fromAddressId);
+   }
+
+
+   /*******************************************************************************
+    ** Fluent setter for fromAddressId, a row of email_provider_sender_address that
+    ** must belong to the resolved provider and be enabled.
+    *******************************************************************************/
+   public EmailRequest withFromAddressId(Integer fromAddressId)
+   {
+      this.fromAddressId = fromAddressId;
+      return (this);
+   }
+
+
    /*******************************************************************************
     ** Getter for replyTo.
     *******************************************************************************/
@@ -590,4 +612,19 @@ public class EmailRequest
       this.securityValues = securityValues;
       return (this);
    }
+
+   /*******************************************************************************
+    ** A record reference is distinct from an ordinary JSON object.
+    *******************************************************************************/
+   public record RecordVariable(String table, Serializable id)
+   {
+   }
+
+   /*******************************************************************************
+    ** Record bindings, read under the sender session by the service.
+    *******************************************************************************/
+   public Map<String, RecordVariable> getRecordVariables()
+   {
+      return (recordVariables);
+   }
 }

src/main/java/com/kingsrook/qbits/email/outbox/EmailService.java

@@ -30,14 +30,17 @@ import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Locale;
 import java.util.Set;
+import java.util.UUID;
 import com.kingsrook.qbits.email.EmailQBitConfig;
 import com.kingsrook.qbits.email.EmailRuntime;
 import com.kingsrook.qbits.email.metadata.EmailTableCustomizers;
 import com.kingsrook.qbits.email.metadata.EmailTables;
 import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
 import com.kingsrook.qbits.email.permissions.EmailPermissions;
+import com.kingsrook.qbits.email.render.EmailUnsubscribeLinks;
 import com.kingsrook.qbits.email.support.EmailStore;
 import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qbits.email.template.EmailTemplateRenderer;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.actions.permissions.CorePermissionEnforcer;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
@@ -64,7 +67,7 @@ public final class EmailService
    }
 
    /*******************************************************************************
-    ** Queue with the part 1 renderer.
+    ** Queue validated, rendered alternatives with optional versioned templates.
     *******************************************************************************/
    public static EmailSendResult send(EmailRequest request) throws QException
    {
@@ -72,9 +75,17 @@ public final class EmailService
    }
 
    /*******************************************************************************
-    ** Queue with a renderer supplied by the host or a later phase.
+    ** Queue with a host-supplied ad-hoc renderer; templates always use the validated engine.
     *******************************************************************************/
    public static EmailSendResult send(EmailRequest request, EmailRenderer renderer) throws QException
+   {
+      return (send(request, renderer, null));
+   }
+
+   /*******************************************************************************
+    ** Shared enqueue path, including already protected retained content.
+    *******************************************************************************/
+   private static EmailSendResult send(EmailRequest request, EmailRenderer renderer, QRecord retained) throws QException
    {
       EmailQBitConfig config = EmailRuntime.config();
       if(config == null)
@@ -89,20 +100,28 @@ public final class EmailService
       {
          return (refused("An email request is required"));
       }
-      if(request.getTemplateName() != null)
+      EmailTemplateRenderer templateRenderer;
+      QRecord templateContent;
+      try
       {
-         return (refused("templates arrive in part 2"));
+         templateRenderer = request.getTemplateName() == null ? null : EmailTemplateRenderer.prepare(request);
+         templateContent = templateRenderer == null ? retained : templateRenderer.render("pending", "https://example.invalid/unsubscribe/pending", true);
       }
-      if(!request.getVariables().isEmpty() || request.getBrandName() != null)
+      catch(IllegalArgumentException e)
       {
-         return (refused("Template variables and branding arrive in part 2"));
+         return (refused(e.getMessage()));
       }
-      if(request.getSubject() == null || request.getSubject().contains("\r") || request.getSubject().contains("\n")
-         || (request.getMarkdownBody() == null && request.getHtmlBody() == null && request.getTextBody() == null))
+      if(templateRenderer == null && (!request.getVariables().isEmpty() || !request.getRecordVariables().isEmpty()))
+      {
+         return (refused("Variables require a template with a schema"));
+      }
+      if(templateRenderer == null && (request.getSubject() == null || request.getSubject().contains("\r") || request.getSubject().contains("\n")
+         || (request.getMarkdownBody() == null && request.getHtmlBody() == null && request.getTextBody() == null)))
       {
          return (refused("A subject and message body are required; subject must be one line"));
       }
-      EmailCategory category = request.getCategory() == null ? EmailCategory.TRANSACTIONAL : request.getCategory();
+      EmailCategory category = templateContent == null ? (request.getCategory() == null ? EmailCategory.TRANSACTIONAL : request.getCategory())
+         : EmailCategory.valueOf(templateContent.getValueString("category"));
       QBackendTransaction transaction = request.getTransaction();
       boolean sameBackend = transaction == null || request.getTransactionBackendName() == null || config.getBackendName().equals(request.getTransactionBackendName());
       QBackendTransaction queryTransaction = sameBackend ? transaction : null;
@@ -125,21 +144,50 @@ public final class EmailService
       {
          return (new EmailSendResult(null, EmailSendResult.Status.REFUSED, providerErrors));
       }
+      try
+      {
+         if(templateRenderer != null)
+         {
+            templateRenderer.validateProvider(provider);
+         }
+         else if(retained != null && Boolean.TRUE.equals(retained.getValueBoolean("phiApproved")))
+         {
+            EmailTemplateRenderer.checkProvider(provider);
+            com.kingsrook.qbits.email.phi.EmailBodyEncryption.encrypt(null, "subject", "pending");
+         }
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (refused(e.getMessage()));
+      }
       List<String> to;
       List<String> cc;
       List<String> bcc;
       String from;
       String replyTo;
+      QRecord senderRow;
+      try
+      {
+         senderRow = senderRow(provider, SystemWrites.query(EmailTables.SENDER, EmailStore.equal("providerId", provider.getValue("id")), queryTransaction), request);
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (refused(e.getMessage()));
+      }
       try
       {
          to = addresses(request.getTo());
          cc = addresses(request.getCc());
          bcc = addresses(request.getBcc());
-         String sender = request.getFrom() == null ? provider.getValueString("fromAddress") : request.getFrom();
+         String sender = request.getFrom() != null ? request.getFrom() : senderRow != null ? senderRow.getValueString("address") : provider.getValueString("fromAddress");
          from = single(sender);
-         if(request.getFrom() == null && provider.getValueString("fromName") != null)
+         if(request.getFrom() == null)
          {
-            from = new InternetAddress(new InternetAddress(from).getAddress(), provider.getValueString("fromName"), "UTF-8").toString();
+            String name = senderRow != null ? senderRow.getValueString("displayName") : provider.getValueString("fromName");
+            if(name != null && !name.isBlank())
+            {
+               from = new InternetAddress(new InternetAddress(from).getAddress(), name, "UTF-8").toString();
+            }
          }
          String reply = request.getReplyTo() == null ? provider.getValueString("replyTo") : request.getReplyTo();
          replyTo = reply == null ? null : single(reply);
@@ -154,6 +202,18 @@ public final class EmailService
       {
          return (refused("One or more email addresses are invalid"));
       }
+      try
+      {
+         String unsubscribe = EmailUnsubscribeLinks.create("pending", String.join(",", to), category.name());
+         if(unsubscribe != null || retained != null && retained.getValueString("unsubscribeUrl") != null)
+         {
+            EmailUnsubscribeLinks.recipient(String.join(",", to), String.join(",", cc), String.join(",", bcc));
+         }
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (refused(e.getMessage()));
+      }
       if(to.isEmpty() && cc.isEmpty() && bcc.isEmpty())
       {
          return (refused("At least one recipient is required"));
@@ -180,18 +240,45 @@ public final class EmailService
          });
       }
       boolean allSuppressed = to.isEmpty() && cc.isEmpty() && bcc.isEmpty();
-      EmailRenderer.Rendered rendered = renderer.render(request);
+      EmailRenderer.Rendered rendered;
+      QRecord adHocBrand = null;
+      try
+      {
+         rendered = templateContent == null ? renderer.render(request) : new EmailRenderer.Rendered(templateContent.getValueString("htmlBody"), templateContent.getValueString("textBody"));
+         if(templateContent == null)
+         {
+            adHocBrand = com.kingsrook.qbits.email.render.EmailBrands.resolve(request.getBrandName(), null);
+         }
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (refused(e.getMessage()));
+      }
       Instant now = EmailRuntime.clock().instant();
       QRecord row = new QRecord().withValue("providerId", provider.getValue("id"))
          .withValue("status", allSuppressed ? "SUPPRESSED" : "QUEUED").withValue("finishedDate", allSuppressed ? now : null).withValue("attemptCount", 0)
          .withValue("toAddresses", String.join(",", to)).withValue("ccAddresses", String.join(",", cc)).withValue("bccAddresses", String.join(",", bcc))
-         .withValue("fromAddress", from).withValue("replyTo", replyTo).withValue("subject", request.getSubject())
+         .withValue("fromAddress", from).withValue("fromAddressId", senderRow == null ? null : senderRow.getValue("id")).withValue("replyTo", replyTo).withValue("subject", request.getSubject())
          .withValue("htmlBody", rendered.html()).withValue("textBody", rendered.text()).withValue("bodySha256", digest(rendered))
+         .withValue("brandId", adHocBrand == null ? null : adHocBrand.getValue("id"))
          .withValue("category", category.name()).withValue("locale", request.getLocale()).withValue("idempotencyKey", request.getIdempotencyKey())
+         .withValue("rfcMessageId", messageId(request.getIdempotencyKey(), from))
          .withValue("linkedTableName", request.getLinkedTableName()).withValue("linkedRecordId", request.getLinkedRecordId())
          .withValue("senderQbit", request.getSenderQbit()).withValue("senderProcess", request.getSenderProcess())
          .withValue("sendAfter", request.getSendAfter()).withValue("nextAttemptDate", request.getSendAfter() == null ? now : request.getSendAfter())
          .withValue("suppressedAddresses", String.join(",", dropped));
+      if(templateContent != null)
+      {
+         row.getValues().putAll(templateContent.getValues());
+         if(row.getValue("senderQbit") == null && row.getValue("templateId") != null)
+         {
+            ///////////////////////////////////////////////////////////////////////////////
+            // the qbit that registered the template is the sender when none was named //
+            ///////////////////////////////////////////////////////////////////////////////
+            List<QRecord> owner = SystemWrites.query(EmailTables.TEMPLATE, EmailStore.equal("id", row.getValue("templateId")), queryTransaction);
+            row.setValue("senderQbit", owner.isEmpty() ? null : owner.getFirst().getValueString("ownerQbit"));
+         }
+      }
       for(var field : config.getSecurityFields())
       {
          row.setValue(field.getName(), request.getSecurityValues().get(field.getName()));
@@ -202,7 +289,7 @@ public final class EmailService
          {
             try
             {
-               if(insert(row, null).status() == EmailSendResult.Status.REFUSED)
+               if(insert(row, null, templateRenderer).status() == EmailSendResult.Status.REFUSED)
                {
                   throw (new QException("Email after-commit enqueue failed"));
                }
@@ -216,21 +303,70 @@ public final class EmailService
          return (new EmailSendResult(null, allSuppressed ? EmailSendResult.Status.SUPPRESSED : EmailSendResult.Status.QUEUED,
             List.of("Enqueue deferred until caller transaction commits")));
       }
-      return (insert(row, transaction));
+      return (insert(row, transaction, templateRenderer));
+   }
+
+   /*******************************************************************************
+    ** Resend retained content without decrypting it or downgrading PHI policy.
+    ** Snapshot tokens keep the original binding; the new row links to that row.
+    *******************************************************************************/
+   public static EmailSendResult resend(Integer id) throws QException
+   {
+      if(!SystemWrites.active() && !EmailPermissionChecker.has(EmailPermissions.MANAGE))
+      {
+         return (refused("Resending email needs email.manage"));
+      }
+      QRecord row = EmailStore.get(EmailTables.MESSAGE, id, null);
+      if(row == null || row.getValueString("htmlBody") == null && row.getValueString("textBody") == null)
+      {
+         return (refused("Retained message content is unavailable"));
+      }
+      QRecord provider = EmailStore.get(EmailTables.PROVIDER, row.getValueInteger("providerId"), null);
+      if(provider == null)
+      {
+         return (refused("Provider is unavailable"));
+      }
+      EmailRequest request = new EmailRequest().withSubject(row.getValueString("subject")).withHtmlBody(row.getValueString("htmlBody"))
+         .withTextBody(row.getValueString("textBody")).withFrom(row.getValueString("fromAddress")).withFromAddressId(row.getValueInteger("fromAddressId")).withReplyTo(row.getValueString("replyTo"))
+         .withProviderName(provider.getValueString("name")).withCategory(EmailCategory.valueOf(row.getValueString("category")))
+         .withLinkedRecord(EmailTables.MESSAGE, id).withSender("email", "email_resend");
+      if(row.getValueString("toAddresses") != null && !row.getValueString("toAddresses").isBlank())
+      {
+         request.withTo(row.getValueString("toAddresses"));
+      }
+      if(row.getValueString("ccAddresses") != null && !row.getValueString("ccAddresses").isBlank())
+      {
+         request.withCc(row.getValueString("ccAddresses"));
+      }
+      if(row.getValueString("bccAddresses") != null && !row.getValueString("bccAddresses").isBlank())
+      {
+         request.withBcc(row.getValueString("bccAddresses"));
+      }
+      for(var field : EmailRuntime.config().getSecurityFields())
+      {
+         request.getSecurityValues().put(field.getName(), row.getValue(field.getName()));
+      }
+      QRecord content = new QRecord();
+      for(String field : List.of("subject", "htmlBody", "textBody", "variablesSnapshot", "phiApproved", "templateId", "templateVersionId", "brandId", "locale", "category", "unsubscribeUrl"))
+      {
+         content.setValue(field, row.getValue(field));
+      }
+      content.withValue("encryptionSourceId", row.getValueString("id"));
+      return (send(request, ignored -> new EmailRenderer.Rendered(row.getValueString("htmlBody"), row.getValueString("textBody")), content));
    }
 
    /*******************************************************************************
     ** Insert once; the database unique key arbitrates concurrent requests.
     *******************************************************************************/
-   private static EmailSendResult insert(QRecord row, QBackendTransaction caller) throws QException
+   private static EmailSendResult insert(QRecord row, QBackendTransaction caller, EmailTemplateRenderer templateRenderer) throws QException
    {
       if(caller != null)
       {
-         return (insertInTransaction(row, caller));
+         return (insertInTransaction(row, caller, templateRenderer));
       }
       try(QBackendTransaction transaction = QBackendTransaction.openFor(new InsertInput(EmailTables.MESSAGE)))
       {
-         EmailSendResult result = insertInTransaction(row, transaction);
+         EmailSendResult result = insertInTransaction(row, transaction, templateRenderer);
          if(result.status() == EmailSendResult.Status.REFUSED)
          {
             transaction.rollback();
@@ -248,7 +384,7 @@ public final class EmailService
    /*******************************************************************************
     ** Insert using the caller transaction, returning only safe diagnostics.
     *******************************************************************************/
-   private static EmailSendResult insertInTransaction(QRecord row, QBackendTransaction transaction) throws QException
+   private static EmailSendResult insertInTransaction(QRecord row, QBackendTransaction transaction, EmailTemplateRenderer templateRenderer) throws QException
    {
       // A shared provider-row gate prevents a duplicate-key failure from aborting
       // a caller-owned SQL transaction. The unique index remains the final arbiter.
@@ -265,21 +401,58 @@ public final class EmailService
       {
          return (new EmailSendResult(existing.getValueInteger("id"), EmailSendResult.Status.DUPLICATE, List.of()));
       }
-      QRecord inserted;
-      try
-      {
-         inserted = SystemWrites.insert(EmailTables.MESSAGE, List.of(row), transaction).getRecords().get(0);
-      }
-      catch(QException e)
-      {
-         return (refused("Could not queue the email message"));
-      }
+      QRecord inserted = SystemWrites.insert(EmailTables.MESSAGE, List.of(row), transaction).getRecords().get(0);
       if(inserted.getErrors() != null && !inserted.getErrors().isEmpty())
       {
-         return (refused("Could not queue the email message"));
+         throw (new QException("Could not queue the email message"));
+      }
+      try
+      {
+         String unsubscribe = row.getValueString("unsubscribeUrl");
+         if(unsubscribe == null && !"SUPPRESSED".equals(row.getValueString("status"))
+            && (templateRenderer != null || !Boolean.TRUE.equals(row.getValueBoolean("phiApproved"))))
+         {
+            unsubscribe = EmailUnsubscribeLinks.create(inserted.getValueString("id"), row.getValueString("toAddresses"), row.getValueString("category"));
+         }
+         QRecord content;
+         if(templateRenderer != null)
+         {
+            content = templateRenderer.render(inserted.getValueString("id"), unsubscribe, true);
+         }
+         else
+         {
+            content = new QRecord();
+            if(Boolean.TRUE.equals(row.getValueBoolean("phiApproved")))
+            {
+               for(String field : List.of("subject", "htmlBody", "textBody"))
+               {
+                  content.setValue(field, com.kingsrook.qbits.email.phi.EmailBodyEncryption.rebind(row.getValueString(field), field,
+                     row.getValueString("encryptionSourceId"), inserted.getValueString("id")));
+               }
+            }
+            if(unsubscribe != null && row.getValueString("unsubscribeUrl") == null)
+            {
+               String link = "<p><a href=\"" + com.kingsrook.qbits.email.template.EmailTemplateEngine.escape(unsubscribe) + "\">Unsubscribe</a></p>";
+               String html = row.getValueString("htmlBody");
+               java.util.regex.Matcher end = java.util.regex.Pattern.compile("</footer>|</body>", java.util.regex.Pattern.CASE_INSENSITIVE).matcher(html);
+               content.withValue("htmlBody", end.find() ? html.substring(0, end.start()) + link + html.substring(end.start()) : html + link)
+                  .withValue("textBody", row.getValueString("textBody") + "\nUnsubscribe (" + unsubscribe + ")");
+            }
+         }
+         content.withValue("id", inserted.getValue("id")).withValue("unsubscribeUrl", unsubscribe);
+         if(content.getValueString("htmlBody") != null)
+         {
+            content.withValue("bodySha256", digest(new EmailRenderer.Rendered(content.getValueString("htmlBody"), content.getValueString("textBody"))));
+         }
+         EmailStore.update(EmailTables.MESSAGE, content, transaction);
+      }
+      catch(IllegalArgumentException e)
+      {
+         SystemWrites.delete(EmailTables.MESSAGE, EmailStore.equal("id", inserted.getValueInteger("id")), transaction);
+         return (refused(e.getMessage()));
       }
       return (new EmailSendResult(inserted.getValueInteger("id"), "SUPPRESSED".equals(row.getValueString("status"))
-         ? EmailSendResult.Status.SUPPRESSED : EmailSendResult.Status.QUEUED, List.of()));
+         ? EmailSendResult.Status.SUPPRESSED : EmailSendResult.Status.QUEUED, templateRenderer == null ? List.of() : templateRenderer.warnings()));
    }
 
    /*******************************************************************************
@@ -321,6 +494,57 @@ public final class EmailService
       return (result);
    }
 
+   /*******************************************************************************
+    ** The provider sender-address row a request uses, or null for the provider's own
+    ** from address. A chosen id, or a from text, must name an enabled row of this
+    ** provider; once a provider has rows, an explicit from text must match one.
+    ** With neither, an enabled default row wins over the provider's from address.
+    *******************************************************************************/
+   private static QRecord senderRow(QRecord provider, List<QRecord> rows, EmailRequest request)
+   {
+      String refusal = "That from address is not set up for provider " + provider.getValueString("name");
+      String wanted = null;
+      if(request.getFrom() != null && (request.getFromAddressId() != null || !rows.isEmpty()))
+      {
+         try
+         {
+            wanted = new InternetAddress(request.getFrom()).getAddress().toLowerCase(Locale.ROOT);
+         }
+         catch(Exception e)
+         {
+            throw (new IllegalArgumentException("One or more email addresses are invalid"));
+         }
+      }
+      for(QRecord row : rows)
+      {
+         boolean enabled = Boolean.TRUE.equals(row.getValueBoolean("enabled"));
+         if(request.getFromAddressId() != null)
+         {
+            if(request.getFromAddressId().equals(row.getValueInteger("id")))
+            {
+               if(!enabled || wanted != null && !wanted.equals(row.getValueString("address")))
+               {
+                  throw (new IllegalArgumentException(refusal));
+               }
+               return (row);
+            }
+         }
+         else if(wanted != null && enabled && wanted.equals(row.getValueString("address")))
+         {
+            return (row);
+         }
+         else if(request.getFrom() == null && enabled && Boolean.TRUE.equals(row.getValueBoolean("isDefault")))
+         {
+            return (row);
+         }
+      }
+      if(request.getFromAddressId() != null || wanted != null)
+      {
+         throw (new IllegalArgumentException(refusal));
+      }
+      return (null);
+   }
+
    /*******************************************************************************
     ** Strict address parsing, rejecting header injection and local-only addresses.
     *******************************************************************************/
@@ -374,6 +598,42 @@ public final class EmailService
       }
    }
 
+
+
+   /*******************************************************************************
+    ** Create once before insertion. A UUID seeds messages without an idempotency key.
+    ** The mailbox parser ignores display names; malformed domains use a local fallback.
+    *******************************************************************************/
+   static String messageId(String key, String from)
+   {
+      String domain = "qbit-email.local";
+      try
+      {
+         String address = new InternetAddress(from).getAddress();
+         String candidate = address.substring(address.lastIndexOf('@') + 1);
+         if(address.contains("@") && candidate.matches("[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*"))
+         {
+            domain = candidate.toLowerCase(Locale.ROOT);
+         }
+      }
+      catch(Exception e)
+      {
+         // A fallback also supports callers preparing legacy message rows.
+      }
+      try
+      {
+         String seed = key == null ? "qbit-email:" + UUID.randomUUID() : key;
+         String token = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(seed.getBytes(StandardCharsets.UTF_8))).substring(0, 32);
+         return ("<" + token + "@" + domain + ">");
+      }
+      catch(java.security.NoSuchAlgorithmException e)
+      {
+         throw (new IllegalStateException("SHA-256 unavailable"));
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Refusal with no stored row.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/email/permissions/EmailPermissionChecker.java

@@ -21,6 +21,7 @@
 package com.kingsrook.qbits.email.permissions;
 
 
+import com.kingsrook.qbits.email.EmailRuntime;
 import com.kingsrook.qbits.email.metadata.EmailTables;
 import com.kingsrook.qbits.email.processes.EmailProcesses;
 import com.kingsrook.qqq.backend.core.actions.permissions.CustomPermissionChecker;
@@ -30,6 +31,7 @@ import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -58,7 +60,7 @@ public class EmailPermissionChecker implements CustomPermissionChecker
       {
          throw (new QPermissionDeniedException("Email messages and attempts are written only by the email qbit. Use Send Now, Resend or Cancel."));
       }
-      if(!has(needed))
+      if(!has(needed) && !hasTemplateGrant(actionInput, metaData))
       {
          throw (new QPermissionDeniedException("This needs the " + needed + " permission."));
       }
@@ -66,6 +68,36 @@ public class EmailPermissionChecker implements CustomPermissionChecker
 
 
 
+   /*******************************************************************************
+    ** Additional host permissions are restricted to template data and lifecycle.
+    *******************************************************************************/
+   private static boolean hasTemplateGrant(AbstractActionInput input, MetaDataWithPermissionRules metaData)
+   {
+      if(metaData instanceof QTableMetaData table
+         && (EmailTables.TEMPLATE.equals(table.getName()) || EmailTables.VERSION.equals(table.getName())))
+      {
+         return (hasTemplatePermission(input instanceof InsertInput || input instanceof UpdateInput || input instanceof DeleteInput));
+      }
+      if(metaData instanceof QAppMetaData app && EmailRuntime.config() != null && EmailRuntime.config().getAppName().equals(app.getName()))
+      {
+         return (hasTemplatePermission(false));
+      }
+      return (metaData instanceof QProcessMetaData process
+         && (EmailProcesses.NEW_VERSION.equals(process.getName()) || EmailProcesses.ACTIVATE_VERSION.equals(process.getName()))
+         && hasTemplatePermission(true));
+   }
+
+   /*******************************************************************************
+    ** Check only the configured read/write grant, without implying email.manage.
+    *******************************************************************************/
+   public static boolean hasTemplatePermission(boolean write)
+   {
+      var config = EmailRuntime.config();
+      String base = config == null ? null : config.getTemplatePermissionBaseName();
+      QSession session = QContext.getQSession();
+      return (base != null && !base.isBlank() && session != null && session.hasPermission(base + (write ? ".write" : ".read")));
+   }
+
    /*******************************************************************************
     ** The permission an action needs (null: nobody may do it directly).
     *******************************************************************************/
@@ -74,7 +106,7 @@ public class EmailPermissionChecker implements CustomPermissionChecker
       boolean write = actionInput instanceof InsertInput || actionInput instanceof UpdateInput || actionInput instanceof DeleteInput;
       if(metaData instanceof QTableMetaData table)
       {
-         if(EmailTables.PROVIDER.equals(table.getName()))
+         if(EmailTables.PROVIDER.equals(table.getName()) || EmailTables.SENDER.equals(table.getName()))
          {
             return (EmailPermissions.ADMIN);
          }

src/main/java/com/kingsrook/qbits/email/phi/EmailBodyEncryption.java

@@ -0,0 +1,137 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.phi;
+
+
+import javax.crypto.Cipher;
+import javax.crypto.spec.GCMParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.SecureRandom;
+import java.util.Base64;
+import com.kingsrook.qbits.email.EmailRuntime;
+
+
+/*******************************************************************************
+ ** Stateless AES-256-GCM body protection. Only the dispatcher decrypts content.
+ *******************************************************************************/
+public final class EmailBodyEncryption
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailBodyEncryption()
+   {
+   }
+
+   /*******************************************************************************
+    ** Resolve the deployment key, never retaining it between operations.
+    *******************************************************************************/
+   private static SecretKeySpec key() throws Exception
+   {
+      String secret = EmailRuntime.config().getSecretResolver().apply("QQQ_EMAIL_BODY_KEY");
+      if(secret == null || secret.isBlank())
+      {
+         throw (new IllegalArgumentException("PHI email needs QQQ_EMAIL_BODY_KEY"));
+      }
+      return (new SecretKeySpec(MessageDigest.getInstance("SHA-256").digest(secret.getBytes(StandardCharsets.UTF_8)), "AES"));
+   }
+
+   /*******************************************************************************
+    ** Encrypt with a fresh 96-bit nonce and 128-bit authentication tag.
+    *******************************************************************************/
+   public static String encrypt(String value, String column, String messageId)
+   {
+      try
+      {
+         SecretKeySpec key = key();
+         if(value == null)
+         {
+            return (null);
+         }
+         byte[] iv = new byte[12];
+         new SecureRandom().nextBytes(iv);
+         Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+         cipher.init(Cipher.ENCRYPT_MODE, key, new GCMParameterSpec(128, iv));
+         cipher.updateAAD(aad(column, messageId));
+         byte[] encrypted = cipher.doFinal(value.getBytes(StandardCharsets.UTF_8));
+         return ("enc:v1:" + Base64.getUrlEncoder().withoutPadding().encodeToString(ByteBuffer.allocate(iv.length + encrypted.length).put(iv).put(encrypted).array()));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("PHI email needs QQQ_EMAIL_BODY_KEY"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Authenticate before exposing plaintext. Failures never echo ciphertext.
+    *******************************************************************************/
+   public static String decrypt(String value, String column, String messageId)
+   {
+      if(value == null || !value.startsWith("enc:v1:"))
+      {
+         return (value);
+      }
+      try
+      {
+         ByteBuffer bytes = ByteBuffer.wrap(Base64.getUrlDecoder().decode(value.substring(7)));
+         byte[] iv = new byte[12];
+         bytes.get(iv);
+         byte[] encrypted = new byte[bytes.remaining()];
+         bytes.get(encrypted);
+         Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+         cipher.init(Cipher.DECRYPT_MODE, key(), new GCMParameterSpec(128, iv));
+         cipher.updateAAD(aad(column, messageId));
+         return (new String(cipher.doFinal(encrypted), StandardCharsets.UTF_8));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Encrypted email body could not be opened"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Bind ciphertext to its storage table, column and message identity.
+    *******************************************************************************/
+   private static byte[] aad(String column, String messageId)
+   {
+      String storageColumn = switch(column)
+      {
+         case "subject" -> "subject";
+         case "htmlBody" -> "html_body";
+         case "textBody" -> "text_body";
+         default -> throw (new IllegalArgumentException("Unknown protected email column"));
+      };
+      return (("email_message\n" + storageColumn + "\n" + java.util.Objects.requireNonNull(messageId)).getBytes(StandardCharsets.UTF_8));
+   }
+
+   /*******************************************************************************
+    ** Authenticate and rebind retained ciphertext without exposing plaintext to
+    ** the resend caller. Only delivery callers receive decrypted content.
+    *******************************************************************************/
+   public static String rebind(String value, String column, String oldMessageId, String newMessageId)
+   {
+      return (encrypt(decrypt(value, column, oldMessageId), column, newMessageId));
+   }
+
+}

src/main/java/com/kingsrook/qbits/email/phi/EmailClassifications.java

@@ -0,0 +1,109 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.phi;
+
+
+import com.kingsrook.qbits.email.EmailQBitConfig;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** STAND-IN(core=#1142, removeBy=RC.7). Core classification wins when available;
+ ** overrides then schema declarations provide the RC.5 compatibility contract.
+ *******************************************************************************/
+public final class EmailClassifications
+{
+   /*******************************************************************************
+    ** Ordered data sensitivity.
+    *******************************************************************************/
+   public enum Level
+   {
+      PUBLIC, CONFIDENTIAL, PII, PHI
+   }
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailClassifications()
+   {
+   }
+
+   /*******************************************************************************
+    ** Resolve a field without a compile-time dependency on unreleased core.
+    *******************************************************************************/
+   public static Level ofField(QTableMetaData table, String field, String declared, EmailQBitConfig config)
+   {
+      if(table != null && field != null)
+      {
+         try
+         {
+            Class<?> core = Class.forName("com.kingsrook.qqq.backend.core.actions.ai.AiDataClassifications");
+            Object value = core.getMethod("ofField", QTableMetaData.class, String.class).invoke(null, table, field);
+            if(value instanceof Enum<?> level)
+            {
+               return (Level.valueOf(level.name()));
+            }
+         }
+         catch(ClassNotFoundException e)
+         {
+            // Expected on RC.5; use the explicit stand-in configuration.
+         }
+         catch(ReflectiveOperationException | IllegalArgumentException e)
+         {
+            throw (new IllegalArgumentException("Field classification is unavailable"));
+         }
+         Level override = config.getClassificationOverrides().get(table.getName() + "." + field);
+         if(override != null)
+         {
+            return (override);
+         }
+      }
+      return (declared == null ? Level.PUBLIC : Level.valueOf(declared));
+   }
+
+   /*******************************************************************************
+    ** Schema declarations alone cannot attest a record's classification source.
+    *******************************************************************************/
+   public static boolean hasSource(QTableMetaData table, String field, EmailQBitConfig config)
+   {
+      if(config.getClassificationOverrides().containsKey(table.getName() + "." + field))
+      {
+         return (true);
+      }
+      try
+      {
+         Class<?> core = Class.forName("com.kingsrook.qqq.backend.core.actions.ai.AiDataClassifications");
+         return (core.getMethod("ofField", QTableMetaData.class, String.class).invoke(null, table, field) instanceof Enum<?>);
+      }
+      catch(ReflectiveOperationException e)
+      {
+         return (false);
+      }
+   }
+
+   /*******************************************************************************
+    ** PII has the same email approval requirement as PHI.
+    *******************************************************************************/
+   public static boolean sensitive(Level level)
+   {
+      return (level == Level.PII || level == Level.PHI);
+   }
+}

src/main/java/com/kingsrook/qbits/email/phi/EmailValueTokens.java

@@ -0,0 +1,149 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.phi;
+
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.Base64;
+import java.util.List;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** STAND-IN(core=#1161-impl, removeBy=RC.7). Mirrors ClassifiedValueTokens.
+ ** Tokens are comparisons, never recoverable snapshots. No secret is retained.
+ *******************************************************************************/
+public final class EmailValueTokens
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailValueTokens()
+   {
+   }
+
+   /*******************************************************************************
+    ** Bind to table, field and record identity. TODO core: wipe-rule record
+    ** fields will produce shred:v1; context values must never use shred:v1.
+    *******************************************************************************/
+   public static String forRecordField(QTableMetaData table, QFieldMetaData field, Serializable pk, Serializable value)
+   {
+      return (token(List.of(table.getName(), field.getName(), String.valueOf(pk)), value));
+   }
+
+   /*******************************************************************************
+    ** Non-record low-entropy inputs cannot yield dictionary-testable tokens.
+    *******************************************************************************/
+   public static String forContext(List<String> bindingParts, Serializable value)
+   {
+      if(value instanceof Boolean || canonical(value).codePoints().distinct().count() < 4)
+      {
+         return (changed());
+      }
+      return (token(bindingParts, value));
+   }
+
+   /*******************************************************************************
+    ** Deliberately non-verifiable marker.
+    *******************************************************************************/
+   public static String changed()
+   {
+      return ("changed:v1");
+   }
+
+   /*******************************************************************************
+    ** Verify only a genuine keyed token, with constant-time comparison.
+    *******************************************************************************/
+   public static boolean verifyRecordField(QTableMetaData table, QFieldMetaData field, Serializable pk, Serializable value, String token)
+   {
+      return (matches(token, forRecordField(table, field, pk, value)));
+   }
+
+   /*******************************************************************************
+    ** Verify a context token, never changed or shred markers.
+    *******************************************************************************/
+   public static boolean verifyContext(List<String> bindingParts, Serializable value, String token)
+   {
+      return (matches(token, forContext(bindingParts, value)));
+   }
+
+   /*******************************************************************************
+    ** Stable canonical representation shared with future core.
+    *******************************************************************************/
+   public static String canonical(Serializable value)
+   {
+      if(value instanceof BigDecimal decimal)
+      {
+         return (decimal.stripTrailingZeros().toPlainString());
+      }
+      return (ValueUtils.getValueAsString(value));
+   }
+
+   /*******************************************************************************
+    ** Construct the versioned HMAC without logging key or input.
+    *******************************************************************************/
+   private static String token(List<String> parts, Serializable value)
+   {
+      try
+      {
+         String secret = EmailRuntime.config().getSecretResolver().apply("QQQ_AUDIT_HMAC_KEY");
+         if(secret == null || secret.isBlank())
+         {
+            return (changed());
+         }
+         byte[] key = Base64.getDecoder().decode(secret);
+         String keyId = EmailRuntime.config().getSecretResolver().apply("QQQ_AUDIT_HMAC_KEY_ID");
+         if(keyId == null || keyId.isBlank())
+         {
+            keyId = "env1";
+         }
+         Mac mac = Mac.getInstance("HmacSHA256");
+         mac.init(new SecretKeySpec(key, "HmacSHA256"));
+         List<String> binding = new ArrayList<>(parts);
+         binding.add(canonical(value));
+         return ("hmac:v1:" + keyId + ":" + Base64.getUrlEncoder().withoutPadding()
+            .encodeToString(mac.doFinal(String.join("\u001f", binding).getBytes(StandardCharsets.UTF_8))));
+      }
+      catch(Exception e)
+      {
+         // An unavailable or malformed audit key must not reveal the value.
+         return (changed());
+      }
+   }
+
+   /*******************************************************************************
+    ** Compare only HMAC tokens, never sentinel strings.
+    *******************************************************************************/
+   private static boolean matches(String supplied, String computed)
+   {
+      return (supplied != null && supplied.startsWith("hmac:v1:") && computed.startsWith("hmac:v1:")
+         && MessageDigest.isEqual(supplied.getBytes(StandardCharsets.UTF_8), computed.getBytes(StandardCharsets.UTF_8)));
+   }
+}

src/main/java/com/kingsrook/qbits/email/processes/EmailProcesses.java

@@ -33,7 +33,6 @@ import com.kingsrook.qbits.email.EmailRuntime;
 import com.kingsrook.qbits.email.delivery.EmailDispatcher;
 import com.kingsrook.qbits.email.metadata.EmailTables;
 import com.kingsrook.qbits.email.outbox.EmailCategory;
-import com.kingsrook.qbits.email.outbox.EmailRenderer;
 import com.kingsrook.qbits.email.outbox.EmailRequest;
 import com.kingsrook.qbits.email.outbox.EmailSendResult;
 import com.kingsrook.qbits.email.outbox.EmailService;
@@ -76,15 +75,24 @@ import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwith
  *******************************************************************************/
 public final class EmailProcesses
 {
+   public static final String NEW_VERSION = "email_new_version";
+   public static final String ACTIVATE_VERSION = "email_activate_version";
+   public static final String APPROVE_PHI = "email_approve_phi";
    public static final String RESEND = "email_resend";
    public static final String CANCEL = "email_cancel";
    public static final String SEND_NOW = "email_send_now";
    public static final String SEND_TEST = "email_send_test";
+   public static final String SEND_AD_HOC = "email_send_ad_hoc";
    public static final String SEND_TEMPLATED = "email_send_templated";
    public static final String DISPATCH = "email_dispatch";
    public static final String MAINTAIN = "email_maintain";
+   public static final String REPROCESS = "email_reprocess_webhook";
+   public static final String PROCESS_WEBHOOKS = "email_process_webhooks";
    public static final String RETENTION = "email_retention";
 
+   /** Process value the send-test prepare step sets to the selected provider id; the from address filter falls back to it. */
+   public static final String PROVIDER_FILTER_VALUE = "possibleValueFilterValueId";
+
    /*******************************************************************************
     ** Utility class.
     *******************************************************************************/
@@ -99,8 +107,8 @@ public final class EmailProcesses
    {
       return (switch(name)
       {
-         case RESEND, CANCEL, SEND_NOW -> EmailPermissions.MANAGE;
-         case SEND_TEMPLATED -> EmailPermissions.SEND;
+         case REPROCESS, RESEND, CANCEL, SEND_NOW, NEW_VERSION, ACTIVATE_VERSION -> EmailPermissions.MANAGE;
+         case SEND_TEMPLATED, SEND_AD_HOC -> EmailPermissions.SEND;
          default -> EmailPermissions.ADMIN;
       });
    }
@@ -111,20 +119,38 @@ public final class EmailProcesses
    public static List<QProcessMetaData> processes(EmailQBitConfig config)
    {
       QProcessMetaData test = action(SEND_TEST, "Send Test Email", EmailTables.PROVIDER);
-      test.withStep(0, new QFrontendStepMetaData().withName("input").withLabel("Recipient")
+      test.withStep(0, new QBackendStepMetaData().withName("prepare").withCode(new QCodeReference(SendTestPrepareStep.class)));
+      test.withStep(1, new QFrontendStepMetaData().withName("input").withLabel("Recipient")
          .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))
-         .withFormField(new QFieldMetaData("toAddress", QFieldType.STRING).withLabel("To address").withIsRequired(true)));
+         .withFormField(new QFieldMetaData("toAddress", QFieldType.STRING).withLabel("To address").withIsRequired(true))
+         .withFormField(new QFieldMetaData("fromAddressId", QFieldType.INTEGER).withLabel("From address").withPossibleValueSourceName(EmailTables.SENDER)
+            .withPossibleValueSourceFilter(EmailStore.equal("providerId", "${input.id}??${processValues." + PROVIDER_FILTER_VALUE + "}"))));
       QFunctionInputMetaData inputs = new QFunctionInputMetaData();
+      QFunctionInputMetaData adHocInputs = new QFunctionInputMetaData();
       for(String field : List.of("templateName", "to", "cc", "bcc", "replyTo", "subject", "markdownBody", "htmlBody", "textBody", "providerName", "brandName",
-         "category", "variablesJson", "linkedTableName", "linkedRecordId", "idempotencyKey"))
+         "locale", "variablesJson", "recordVariablesJson", "linkedTableName", "linkedRecordId", "idempotencyKey"))
       {
          inputs.withField(new QFieldMetaData(field, QFieldType.STRING));
+         adHocInputs.withField(new QFieldMetaData(field, QFieldType.STRING));
       }
+      adHocInputs.withField(new QFieldMetaData("category", QFieldType.STRING));
+      for(QFunctionInputMetaData target : List.of(inputs, adHocInputs))
+      {
+         target.withField(new QFieldMetaData("providerId", QFieldType.INTEGER).withPossibleValueSourceName(EmailTables.PROVIDER));
+         target.withField(new QFieldMetaData("fromAddressId", QFieldType.INTEGER).withPossibleValueSourceName(EmailTables.SENDER)
+            .withPossibleValueSourceFilter(EmailStore.equal("providerId", "${input.providerId}")));
+      }
+      QProcessMetaData adHoc = new QProcessMetaData().withName(SEND_AD_HOC).withLabel("Send Ad Hoc Email").withIsHidden(true)
+         .withPermissionRules(EmailTables.permissionRules())
+         .withStep(new QBackendStepMetaData().withName("send").withCode(new QCodeReference(SendStep.class)).withInputData(adHocInputs));
       QProcessMetaData send = new QProcessMetaData().withName(SEND_TEMPLATED).withLabel("Send Email").withIsHidden(true)
          .withPermissionRules(EmailTables.permissionRules())
          .withStep(new QBackendStepMetaData().withName("send").withCode(new QCodeReference(SendStep.class)).withInputData(inputs));
       return (List.of(action(RESEND, "Resend", EmailTables.MESSAGE), action(CANCEL, "Cancel", EmailTables.MESSAGE),
-         action(SEND_NOW, "Send Now", EmailTables.MESSAGE), test, send,
+         action(SEND_NOW, "Send Now", EmailTables.MESSAGE), test, send, adHoc,
+         action(NEW_VERSION, "New Version", EmailTables.TEMPLATE), action(ACTIVATE_VERSION, "Activate Version", EmailTables.VERSION),
+         action(APPROVE_PHI, "Approve For PHI", EmailTables.VERSION),
+         action(REPROCESS, "Reprocess", EmailTables.INBOX), scheduled(config, PROCESS_WEBHOOKS, "Process Email Webhooks", 30),
          scheduled(config, DISPATCH, "Dispatch Email", config.getDispatchIntervalSeconds()),
          scheduled(config, MAINTAIN, "Maintain Email", 300), scheduled(config, RETENTION, "Email Retention", 86400)));
    }
@@ -164,6 +190,18 @@ public final class EmailProcesses
     *******************************************************************************/
    private static boolean eligible(String process, QRecord row)
    {
+      if(REPROCESS.equals(process))
+      {
+         return ("FAILED".equals(row.getValueString("status")));
+      }
+      if(NEW_VERSION.equals(process))
+      {
+         return (true);
+      }
+      if(ACTIVATE_VERSION.equals(process) || APPROVE_PHI.equals(process))
+      {
+         return ("DRAFT".equals(row.getValueString("status")) || APPROVE_PHI.equals(process) && "ACTIVE".equals(row.getValueString("status")));
+      }
       if(SEND_TEST.equals(process))
       {
          return (Boolean.TRUE.equals(row.getValueBoolean("enabled")));
@@ -188,12 +226,30 @@ public final class EmailProcesses
        ** Filter rows and explain skipped records.
        *******************************************************************************/
       @Override
-      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output)
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
       {
          for(QRecord row : input.getRecords())
          {
             boolean valid = eligible(input.getProcessName(), row);
-            lines.add(new ProcessSummaryLine(valid ? Status.OK : Status.INFO, 1, valid ? "record will be processed" : "record skipped: status or retained content does not permit this action"));
+            String diagnostic = valid ? "record will be processed" : "record skipped: status or retained content does not permit this action";
+            if(valid && List.of(NEW_VERSION, ACTIVATE_VERSION, APPROVE_PHI).contains(input.getProcessName()))
+            {
+               try
+               {
+                  QRecord template = NEW_VERSION.equals(input.getProcessName()) ? row : EmailStore.get(EmailTables.TEMPLATE, row.getValueInteger("templateId"), null);
+                  com.kingsrook.qbits.email.template.EmailVersions.requireEdit(template, APPROVE_PHI.equals(input.getProcessName()));
+                  if(ACTIVATE_VERSION.equals(input.getProcessName()))
+                  {
+                     com.kingsrook.qbits.email.template.EmailVersions.validate(template, row);
+                  }
+               }
+               catch(IllegalArgumentException e)
+               {
+                  valid = false;
+                  diagnostic = e.getMessage();
+               }
+            }
+            lines.add(new ProcessSummaryLine(valid ? Status.OK : Status.INFO, 1, diagnostic));
             if(valid)
             {
                output.getRecords().add(row);
@@ -228,16 +284,29 @@ public final class EmailProcesses
          for(QRecord row : input.getRecords())
          {
             Integer id = row.getValueInteger("id");
-            QRecord current = EmailStore.get(SEND_TEST.equals(process) ? EmailTables.PROVIDER : EmailTables.MESSAGE, id, null);
+            QRecord current = EmailStore.get(NEW_VERSION.equals(process) ? EmailTables.TEMPLATE : List.of(ACTIVATE_VERSION, APPROVE_PHI).contains(process) ? EmailTables.VERSION
+               : REPROCESS.equals(process) ? EmailTables.INBOX : SEND_TEST.equals(process) ? EmailTables.PROVIDER : EmailTables.MESSAGE, id, null);
             String result = "Skipped";
             if(current != null && eligible(process, current))
             {
                result = switch(process)
                {
+                  case NEW_VERSION -> "Created DRAFT " + com.kingsrook.qbits.email.template.EmailVersions.newVersion(id).getValueInteger("versionNumber");
+                  case ACTIVATE_VERSION ->
+                  {
+                     com.kingsrook.qbits.email.template.EmailVersions.activate(id);
+                     yield "ACTIVE";
+                  }
+                  case APPROVE_PHI ->
+                  {
+                     com.kingsrook.qbits.email.template.EmailVersions.approve(id);
+                     yield "Approved for PHI";
+                  }
+                  case REPROCESS -> com.kingsrook.qbits.email.tracking.EmailInboxProcessor.reprocess(id) ? "PENDING" : "Skipped";
                   case SEND_NOW -> new EmailDispatcher().sendNow(id).name();
                   case CANCEL -> cancel(id) ? "CANCELLED" : "Skipped";
                   case RESEND -> resend(current).status().name();
-                  case SEND_TEST -> sendTest(current, input.getValueString("toAddress"));
+                  case SEND_TEST -> sendTest(current, input.getValueString("toAddress"), input.getValueInteger("fromAddressId"));
                   default -> "Skipped";
                };
             }
@@ -285,45 +354,51 @@ public final class EmailProcesses
     *******************************************************************************/
    private static EmailSendResult resend(QRecord row) throws QException
    {
-      QRecord provider = EmailStore.get(EmailTables.PROVIDER, row.getValueInteger("providerId"), null);
-      EmailRequest request = new EmailRequest().withSubject(row.getValueString("subject")).withHtmlBody(row.getValueString("htmlBody"))
-         .withTextBody(row.getValueString("textBody")).withFrom(row.getValueString("fromAddress")).withReplyTo(row.getValueString("replyTo"))
-         .withProviderName(provider.getValueString("name")).withCategory(EmailCategory.valueOf(row.getValueString("category")))
-         .withLinkedRecord(EmailTables.MESSAGE, row.getValue("id")).withSender("email", RESEND);
-      for(String field : List.of("toAddresses", "ccAddresses", "bccAddresses"))
-      {
-         String value = row.getValueString(field);
-         if(value != null && !value.isBlank())
-         {
-            switch(field)
-            {
-               case "toAddresses" -> request.withTo(value);
-               case "ccAddresses" -> request.withCc(value);
-               default -> request.withBcc(value);
-            }
-         }
-      }
-      for(var field : EmailRuntime.config().getSecurityFields())
-      {
-         request.getSecurityValues().put(field.getName(), row.getValue(field.getName()));
-      }
-      return (EmailService.send(request, ignored -> new EmailRenderer.Rendered(row.getValueString("htmlBody"), row.getValueString("textBody"))));
+      return (EmailService.resend(row.getValueInteger("id")));
    }
 
    /*******************************************************************************
     ** Queue and dispatch a fixed provider test message.
     *******************************************************************************/
-   private static String sendTest(QRecord provider, String to) throws QException
+   private static String sendTest(QRecord provider, String to, Integer fromAddressId) throws QException
    {
       if(to == null)
       {
          return ("REFUSED: a to address is required");
       }
-      EmailSendResult result = EmailService.send(new EmailRequest().withProviderName(provider.getValueString("name")).withTo(to)
+      EmailSendResult result = EmailService.send(new EmailRequest().withProviderName(provider.getValueString("name")).withTo(to).withFromAddressId(fromAddressId)
          .withSubject("Email delivery test").withMarkdownBody("This is a test of your email provider.").withSender("email", SEND_TEST));
       return (result.status() == EmailSendResult.Status.QUEUED ? new EmailDispatcher().sendNow(result.messageId()).name() : result.status().name());
    }
 
+   /*******************************************************************************
+    ** Seeds the from address possible-value filter: a record action's form has no
+    ** record id, so a single selected provider id becomes a process value that the
+    ** filter reads after the form's own ${input.id}.
+    *******************************************************************************/
+   public static class SendTestPrepareStep implements BackendStep
+   {
+      /*******************************************************************************
+       ** Expose the selected provider id when exactly one provider is selected.
+       *******************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         String ids = input.getValueString("recordIds");
+         if(ids != null && !ids.contains(","))
+         {
+            try
+            {
+               output.addValue(PROVIDER_FILTER_VALUE, Integer.valueOf(ids.trim()));
+            }
+            catch(NumberFormatException e)
+            {
+               // Not a single id: the filter stays open and the review step still validates the selection.
+            }
+         }
+      }
+   }
+
    /*******************************************************************************
     ** Backend sending API with inputs declared as QQQ fields.
     *******************************************************************************/
@@ -335,10 +410,20 @@ public final class EmailProcesses
       @Override
       public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
       {
-         EmailRequest request = new EmailRequest().withTemplateName(input.getValueString("templateName"))
+         String providerName = input.getValueString("providerName");
+         if(input.getValueInteger("providerId") != null)
+         {
+            QRecord provider = EmailStore.get(EmailTables.PROVIDER, input.getValueInteger("providerId"), null);
+            if(provider == null || providerName != null && !providerName.equals(provider.getValueString("name")))
+            {
+               throw (new QException("providerId does not match an existing provider named providerName"));
+            }
+            providerName = provider.getValueString("name");
+         }
+         EmailRequest request = new EmailRequest().withTemplateName(input.getValueString("templateName")).withFromAddressId(input.getValueInteger("fromAddressId"))
             .withSubject(input.getValueString("subject")).withMarkdownBody(input.getValueString("markdownBody"))
             .withHtmlBody(input.getValueString("htmlBody")).withTextBody(input.getValueString("textBody"))
-            .withReplyTo(input.getValueString("replyTo")).withProviderName(input.getValueString("providerName"))
+            .withReplyTo(input.getValueString("replyTo")).withProviderName(providerName)
             .withBrandName(input.getValueString("brandName")).withIdempotencyKey(input.getValueString("idempotencyKey"))
             .withLinkedRecord(input.getValueString("linkedTableName"), input.getValueString("linkedRecordId"));
          if(input.getValueString("to") != null)
@@ -355,9 +440,25 @@ public final class EmailProcesses
          }
          if(input.getValueString("variablesJson") != null)
          {
-            request.withVariable("variablesJson", input.getValueString("variablesJson"));
+            request.withVariables(com.kingsrook.qbits.email.template.VariableSchema.values(input.getValueString("variablesJson")));
          }
-         if(input.getValueString("category") != null)
+         if(input.getValueString("locale") != null)
+         {
+            request.withLocale(input.getValueString("locale"));
+         }
+         if(input.getValueString("recordVariablesJson") != null)
+         {
+            var bindings = com.kingsrook.qbits.email.template.VariableSchema.values(input.getValueString("recordVariablesJson"));
+            for(var binding : bindings.entrySet())
+            {
+               if(!(binding.getValue() instanceof Map<?, ?> ref) || !(ref.get("table") instanceof String table) || !(ref.get("id") instanceof Serializable id))
+               {
+                  throw (new QException("Record variables need table and id"));
+               }
+               request.withRecordVariable(binding.getKey(), table, id);
+            }
+         }
+         if(request.getTemplateName() == null && input.getValueString("category") != null)
          {
             try
             {
@@ -388,6 +489,7 @@ public final class EmailProcesses
       {
          switch(input.getProcessName())
          {
+            case PROCESS_WEBHOOKS -> new com.kingsrook.qbits.email.tracking.EmailInboxProcessor().runOnce();
             case RETENTION -> retain();
             case MAINTAIN -> new EmailDispatcher().maintain();
             default -> new EmailDispatcher().runOnce();
@@ -397,6 +499,8 @@ public final class EmailProcesses
 
    /*******************************************************************************
     ** Clear retained bodies and optionally delete final messages and their attempts.
+    ** NOTIFICATION and MARKETING messages are never deleted (their unsubscribe links must
+    ** keep working); at message retention only their bodies and variable snapshot are cleared.
     *******************************************************************************/
    public static void retain() throws QException
    {
@@ -421,18 +525,35 @@ public final class EmailProcesses
          {
             continue;
          }
-         if(config.getMessageRetentionDays() > 0 && finalDate.isBefore(now.minus(Duration.ofDays(config.getMessageRetentionDays()))))
+         boolean expired = config.getMessageRetentionDays() > 0 && finalDate.isBefore(now.minus(Duration.ofDays(config.getMessageRetentionDays())));
+         boolean optOut = List.of("NOTIFICATION", "MARKETING").contains(row.getValueString("category"));
+         if(expired && !optOut)
          {
             try(QBackendTransaction transaction = QBackendTransaction.openFor(new UpdateInput(EmailTables.MESSAGE)))
             {
+               if(row.getValueInteger("providerId") != null)
+               {
+                  com.kingsrook.qbits.email.tracking.EmailTrackingStore.lock(row.getValueInteger("providerId"), transaction);
+               }
+               SystemWrites.delete(EmailTables.EVENT, EmailStore.equal("messageId", row.getValueInteger("id")), transaction);
                SystemWrites.delete(EmailTables.ATTEMPT, EmailStore.equal("messageId", row.getValueInteger("id")), transaction);
                SystemWrites.delete(EmailTables.MESSAGE, EmailStore.equal("id", row.getValueInteger("id")), transaction);
                transaction.commit();
             }
          }
-         else if(finalDate.isBefore(now.minus(Duration.ofDays(config.getBodyRetentionDays()))) && (row.getValue("htmlBody") != null || row.getValue("textBody") != null))
+         else if(expired || finalDate.isBefore(now.minus(Duration.ofDays(config.getBodyRetentionDays()))))
          {
-            SystemWrites.updateOne(EmailTables.MESSAGE, new QRecord().withValue("id", row.getValue("id")).withValue("htmlBody", null).withValue("textBody", null));
+            // Notification and marketing rows are never deleted, so their unsubscribe links keep working; only content goes.
+            boolean clearSnapshot = expired && row.getValue("variablesSnapshot") != null;
+            if(row.getValue("htmlBody") != null || row.getValue("textBody") != null || clearSnapshot)
+            {
+               QRecord update = new QRecord().withValue("id", row.getValue("id")).withValue("htmlBody", null).withValue("textBody", null);
+               if(clearSnapshot)
+               {
+                  update.withValue("variablesSnapshot", null);
+               }
+               SystemWrites.updateOne(EmailTables.MESSAGE, update);
+            }
          }
       }
    }

src/main/java/com/kingsrook/qbits/email/render/ContrastCheck.java

@@ -0,0 +1,112 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import java.util.Locale;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** WCAG relative luminance and AA contrast for both email color schemes.
+ *******************************************************************************/
+public final class ContrastCheck
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private ContrastCheck()
+   {
+   }
+
+   /*******************************************************************************
+    ** Check every actual foreground/background pair in the branded shell.
+    *******************************************************************************/
+   public static void validate(QRecord brand)
+   {
+      check("Text on background", color(brand, "textColor"), color(brand, "backgroundColor"), "light");
+      check("Text on background", color(brand, "darkTextColor"), color(brand, "darkBackgroundColor"), "dark");
+      check("Button text on primary", color(brand, "buttonTextColor"), color(brand, "primaryColor"), "light");
+      check("Button text on primary", color(brand, "darkButtonTextColor"), color(brand, "darkPrimaryColor"), "dark");
+   }
+
+   /*******************************************************************************
+    ** Defaults are neutral and accessible; reject anything except hex colors.
+    *******************************************************************************/
+   public static String color(QRecord brand, String field)
+   {
+      String value = brand.getValueString(field);
+      if(value == null || value.isBlank())
+      {
+         value = switch(field)
+         {
+            case "backgroundColor", "buttonTextColor", "darkTextColor" -> "#ffffff";
+            case "primaryColor" -> "#2459a6";
+            case "darkPrimaryColor" -> color(brand, "primaryColor");
+            case "darkButtonTextColor" -> ratio(color(brand, "buttonTextColor"), color(brand, "darkPrimaryColor")) >= 4.5
+               ? color(brand, "buttonTextColor") : ratio("#000000", color(brand, "darkPrimaryColor")) >= 4.5 ? "#000000" : "#ffffff";
+            default -> "#171717";
+         };
+      }
+      if(!value.matches("#[0-9a-fA-F]{6}"))
+      {
+         throw (new IllegalArgumentException("Brand colors must use six-digit hex values"));
+      }
+      return (value);
+   }
+
+   /*******************************************************************************
+    ** Contrast is independent of which color is lighter.
+    *******************************************************************************/
+   public static double ratio(String first, String second)
+   {
+      double a = luminance(first);
+      double b = luminance(second);
+      return ((Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05));
+   }
+
+   /*******************************************************************************
+    ** sRGB linearization and weighted luminance.
+    *******************************************************************************/
+   private static double luminance(String color)
+   {
+      double[] weights = {0.2126, 0.7152, 0.0722};
+      double result = 0;
+      for(int i = 0; i < 3; i++)
+      {
+         double channel = Integer.parseInt(color.substring(1 + i * 2, 3 + i * 2), 16) / 255.0;
+         result += weights[i] * (channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4));
+      }
+      return (result);
+   }
+
+   /*******************************************************************************
+    ** Author-facing refusal explains the failing scheme and threshold.
+    *******************************************************************************/
+   private static void check(String label, String foreground, String background, String scheme)
+   {
+      double ratio = ratio(foreground, background);
+      if(ratio < 4.5)
+      {
+         throw (new IllegalArgumentException(String.format(Locale.ROOT, "%s is %.1f:1 in %s mode; it needs 4.5:1", label, ratio, scheme)));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/render/EmailBrands.java

@@ -0,0 +1,156 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import java.util.List;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qbits.email.template.VariableSchema;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Brand selection shared by sends, activation and previews.
+ *******************************************************************************/
+public final class EmailBrands
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailBrands()
+   {
+   }
+
+   /*******************************************************************************
+    ** Explicit request, template, app brand, default brand, then neutral.
+    *******************************************************************************/
+   public static QRecord resolve(String requested, QRecord template) throws QException
+   {
+      if(requested != null)
+      {
+         List<QRecord> rows = SystemWrites.query(EmailTables.BRAND, EmailStore.equal("name", requested));
+         if(rows.isEmpty())
+         {
+            throw (new IllegalArgumentException("Unknown email brand"));
+         }
+         return (rows.getFirst());
+      }
+      if(template != null && template.getValueInteger("brandId") != null)
+      {
+         QRecord brand = EmailStore.get(EmailTables.BRAND, template.getValueInteger("brandId"), null);
+         if(brand == null)
+         {
+            throw (new IllegalArgumentException("Template brand is missing"));
+         }
+         return (brand);
+      }
+      List<QRecord> brands = SystemWrites.query(EmailTables.BRAND, EmailStore.equal("appName", EmailRuntime.config().getAppName()));
+      if(brands.isEmpty())
+      {
+         brands = SystemWrites.query(EmailTables.BRAND, EmailStore.equal("isDefault", true));
+      }
+      if(brands.size() > 1)
+      {
+         throw (new IllegalArgumentException("More than one default email brand matches"));
+      }
+      return (brands.isEmpty() ? new QRecord().withValue("label", EmailRuntime.config().getAppLabel()).withValue("name", "neutral") : brands.getFirst());
+   }
+
+   /*******************************************************************************
+    ** Refuse unsafe URLs and inaccessible colors before a brand is saved.
+    *******************************************************************************/
+   public static void validate(QRecord brand)
+   {
+      ContrastCheck.validate(brand);
+      for(String field : List.of("logoUrl", "logoDarkUrl", "siteUrl"))
+      {
+         String value = brand.getValueString(field);
+         if(value != null && !value.isBlank())
+         {
+            VariableSchema.url(value);
+            if(!"siteUrl".equals(field))
+            {
+               https(value);
+            }
+         }
+      }
+      social(brand);
+   }
+
+   /*******************************************************************************
+    ** Parse the small social-link list with strict web URLs.
+    *******************************************************************************/
+   public static List<java.util.Map<String, String>> social(QRecord brand)
+   {
+      try
+      {
+         String json = brand.getValueString("socialLinks");
+         if(json == null || json.isBlank())
+         {
+            return (List.of());
+         }
+         var links = new com.fasterxml.jackson.databind.ObjectMapper().readValue(json,
+            new com.fasterxml.jackson.core.type.TypeReference<List<java.util.Map<String, String>>>() {});
+         links.forEach(link -> https(link.get("url")));
+         return (links);
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Social links need labels and https URLs"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Logos and social destinations require HTTPS at the save boundary.
+    *******************************************************************************/
+   private static void https(String value)
+   {
+      VariableSchema.url(value);
+      if(!"https".equalsIgnoreCase(java.net.URI.create(value).getScheme()))
+      {
+         throw (new IllegalArgumentException("Brand logo and social URLs must use https"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Approved messages restrict every image to the brand site or an explicit host.
+    *******************************************************************************/
+   public static boolean allowedImage(String value, QRecord brand)
+   {
+      try
+      {
+         https(value);
+         String host = java.net.URI.create(value).getHost();
+         String site = brand.getValueString("siteUrl");
+         return (EmailRuntime.config().getAllowedImageHosts().contains(host.toLowerCase(java.util.Locale.ROOT))
+            || site != null && host.equalsIgnoreCase(java.net.URI.create(site).getHost()));
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (false);
+      }
+   }
+
+}

src/main/java/com/kingsrook/qbits/email/render/EmailLayout.java

@@ -0,0 +1,135 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import com.kingsrook.qbits.email.outbox.EmailCategory;
+import com.kingsrook.qbits.email.template.EmailTemplateEngine;
+import com.kingsrook.qbits.email.template.VariableSchema;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Single-column, 600px email shell with inline fallbacks and dark-mode hooks.
+ *******************************************************************************/
+public final class EmailLayout
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailLayout()
+   {
+   }
+
+   /*******************************************************************************
+    ** Render both schemes from the same validated brand.
+    *******************************************************************************/
+   public static String render(String body, String preheader, QRecord brand, EmailCategory category, String unsubscribe)
+   {
+      EmailBrands.validate(brand);
+      String dark = ".email-shell,.email-content{background-color:" + ContrastCheck.color(brand, "darkBackgroundColor")
+         + "!important;color:" + ContrastCheck.color(brand, "darkTextColor") + "!important}.email-button{background-color:"
+         + ContrastCheck.color(brand, "darkPrimaryColor") + "!important}.email-button a{color:" + ContrastCheck.color(brand, "darkButtonTextColor")
+         + "!important}.email-logo-light{display:none!important}.email-logo-dark{display:block!important}";
+      String outlook = "[data-ogsc] .email-content,[data-ogsc] .email-shell,[data-ogsb] .email-content,[data-ogsb] .email-shell{background-color:" + ContrastCheck.color(brand, "darkBackgroundColor")
+         + "!important;color:" + ContrastCheck.color(brand, "darkTextColor") + "!important}[data-ogsc] .email-button,[data-ogsb] .email-button{background-color:"
+         + ContrastCheck.color(brand, "darkPrimaryColor") + "!important}[data-ogsc] .email-button a,[data-ogsb] .email-button a{color:" + ContrastCheck.color(brand, "darkButtonTextColor")
+         + "!important}[data-ogsc] .email-logo-light,[data-ogsb] .email-logo-light{display:none!important}[data-ogsc] .email-logo-dark,[data-ogsb] .email-logo-dark{display:block!important}";
+      return ("<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">"
+         + "<meta name=\"color-scheme\" content=\"light dark\"><meta name=\"supported-color-schemes\" content=\"light dark\">"
+         + "<style>:root{color-scheme:light dark;supported-color-schemes:light dark}@media(max-width:640px){.email-content{padding:16px!important;width:100%!important}}"
+         + "@media(prefers-color-scheme:dark){" + dark + "}" + outlook + "</style></head><body class=\"email-shell\" style=\"margin:0;padding:0;background-color:"
+         + ContrastCheck.color(brand, "backgroundColor") + ";color:" + ContrastCheck.color(brand, "textColor") + "\">"
+         + "<div style=\"display:none;max-height:0;overflow:hidden;opacity:0;mso-hide:all\">" + EmailTemplateEngine.escape(preheader) + "</div>"
+         + "<table role=\"presentation\" width=\"100%\" cellspacing=\"0\" cellpadding=\"0\"><tr><td align=\"center\">"
+         + "<!--[if mso]><table role=\"presentation\" width=\"600\"><tr><td><![endif]-->"
+         + "<table role=\"presentation\" width=\"100%\" cellspacing=\"0\" cellpadding=\"0\" style=\"max-width:600px;table-layout:fixed\"><tr>"
+         + "<td class=\"email-content\" style=\"padding:24px;font-family:Arial,sans-serif;line-height:1.6;overflow-wrap:anywhere;word-break:break-word;background-color:"
+         + ContrastCheck.color(brand, "backgroundColor") + ";color:" + ContrastCheck.color(brand, "textColor") + "\">" + logos(brand)
+         + body + footer(brand, category, unsubscribe) + "</td></tr></table><!--[if mso]></td></tr></table><![endif]--></td></tr></table></body></html>");
+   }
+
+   /*******************************************************************************
+    ** Logo alternatives, with dimensions that never force horizontal overflow.
+    *******************************************************************************/
+   private static String logos(QRecord brand)
+   {
+      String light = brand.getValueString("logoUrl");
+      if(light == null || light.isBlank())
+      {
+         return ("<p><strong>" + EmailTemplateEngine.escape(brand.getValueString("label")) + "</strong></p>");
+      }
+      String dark = brand.getValueString("logoDarkUrl");
+      return (logo(light, brand.getValueString("logoAlt"), dark == null ? "" : "email-logo-light", "block")
+         + (dark == null ? "" : logo(dark, brand.getValueString("logoAlt"), "email-logo-dark", "none")));
+   }
+
+   /*******************************************************************************
+    ** Escaped logo element.
+    *******************************************************************************/
+   private static String logo(String url, String alt, String css, String display)
+   {
+      return ("<img class=\"" + css + "\" src=\"" + EmailTemplateEngine.escape(VariableSchema.url(url)) + "\" alt=\""
+         + EmailTemplateEngine.escape(alt) + "\" width=\"180\" style=\"display:" + display + ";max-width:100%;height:auto\">");
+   }
+
+   /*******************************************************************************
+    ** Category-specific footer, including postal address for marketing.
+    *******************************************************************************/
+   public static String footer(QRecord brand, EmailCategory category, String unsubscribe)
+   {
+      StringBuilder footer = new StringBuilder("<footer style=\"margin-top:24px;font-size:12px;overflow-wrap:anywhere\">");
+      footer.append(EmailMarkdown.render(brand.getValueString("footerMarkdown"), brand));
+      if(category == EmailCategory.MARKETING)
+      {
+         String address = brand.getValueString("postalAddress");
+         if(address == null || address.isBlank())
+         {
+            throw (new IllegalArgumentException("Marketing email needs a brand postal address"));
+         }
+         footer.append("<p>").append(EmailTemplateEngine.escape(address)).append("</p>");
+      }
+      for(var link : EmailBrands.social(brand))
+      {
+         footer.append("<a style=\"color:inherit\" href=\"").append(EmailTemplateEngine.escape(link.get("url"))).append("\">")
+            .append(EmailTemplateEngine.escape(link.get("label"))).append("</a> ");
+      }
+      if((category == EmailCategory.NOTIFICATION || category == EmailCategory.MARKETING) && unsubscribe != null && !unsubscribe.isBlank())
+      {
+         footer.append("<p><a style=\"color:inherit\" href=\"").append(EmailTemplateEngine.escape(unsubscribe)).append("\">Unsubscribe</a></p>");
+      }
+      return (footer.append("</footer>").toString());
+   }
+
+   /*******************************************************************************
+    ** HTML and compiled MJML retain their shell; append opt-out before body end.
+    *******************************************************************************/
+   public static String appendFooter(String html, QRecord brand, EmailCategory category, String unsubscribe)
+   {
+      if(category != EmailCategory.NOTIFICATION && category != EmailCategory.MARKETING)
+      {
+         return (html);
+      }
+      String footer = footer(brand, category, unsubscribe);
+      java.util.regex.Matcher end = java.util.regex.Pattern.compile("</body\\s*>", java.util.regex.Pattern.CASE_INSENSITIVE).matcher(html);
+      return (end.find() ? html.substring(0, end.start()) + footer + html.substring(end.start()) : html + footer);
+   }
+}

src/main/java/com/kingsrook/qbits/email/render/EmailMarkdown.java

@@ -0,0 +1,71 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.commonmark.ext.autolink.AutolinkExtension;
+import org.commonmark.ext.gfm.tables.TablesExtension;
+import org.commonmark.parser.Parser;
+import org.commonmark.renderer.html.HtmlRenderer;
+
+
+/*******************************************************************************
+ ** CommonMark with GFM tables, autolinks and a constrained button attribute.
+ *******************************************************************************/
+public final class EmailMarkdown
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailMarkdown()
+   {
+   }
+
+   /*******************************************************************************
+    ** Raw HTML is escaped and URLs sanitized before adding table buttons.
+    *******************************************************************************/
+   public static String render(String markdown, QRecord brand)
+   {
+      var extensions = List.of(TablesExtension.create(), AutolinkExtension.create());
+      String html = HtmlRenderer.builder().escapeHtml(true).sanitizeUrls(true).extensions(extensions).build()
+         .render(Parser.builder().extensions(extensions).build().parse(markdown == null ? "" : markdown))
+         .replace("<a ", "<a style=\"color:inherit;text-decoration:underline\" ");
+      Matcher links = Pattern.compile("<a[^>]* href=\"([^\"]*)\"[^>]*>((?:(?!</?a\\b)[^\\r\\n])*)</a>\\{\\.button}").matcher(html);
+      StringBuilder result = new StringBuilder();
+      while(links.find())
+      {
+         String button = "<table role=\"presentation\" cellspacing=\"0\" cellpadding=\"0\"><tr><td class=\"email-button\" bgcolor=\""
+            + ContrastCheck.color(brand, "primaryColor") + "\" style=\"border-radius:4px;padding:12px 20px;background-color:"
+            + ContrastCheck.color(brand, "primaryColor") + "\"><a href=\"" + links.group(1) + "\" style=\"display:inline-block;text-decoration:none;color:"
+            + ContrastCheck.color(brand, "buttonTextColor") + ";font-weight:bold\">" + links.group(2) + "</a></td></tr></table>";
+         links.appendReplacement(result, Matcher.quoteReplacement(button));
+      }
+      links.appendTail(result);
+      return (result.toString().replace("<p><table", "<table").replace("</table></p>", "</table>").replace("<table>", "<table style=\"width:100%;table-layout:fixed;border-collapse:collapse\">")
+         .replace("<td>", "<td style=\"padding:6px;border:1px solid #888;overflow-wrap:anywhere\">")
+         .replace("<th>", "<th style=\"padding:6px;border:1px solid #888;overflow-wrap:anywhere\">")
+         .replace("<img ", "<img style=\"max-width:100%;height:auto\" ").replace("<pre>", "<pre style=\"white-space:pre-wrap;overflow-wrap:anywhere\">"));
+   }
+}

src/main/java/com/kingsrook/qbits/email/render/EmailUnsubscribeLinks.java

@@ -0,0 +1,150 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.Base64;
+import java.util.HexFormat;
+import java.util.Locale;
+import java.util.Map;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.template.VariableSchema;
+import jakarta.mail.internet.InternetAddress;
+
+
+/*******************************************************************************
+ ** Queue-time link signing and verification from DESIGN 8.2.
+ *******************************************************************************/
+public final class EmailUnsubscribeLinks
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailUnsubscribeLinks()
+   {
+   }
+
+   /*******************************************************************************
+    ** Bind the message, single mailbox hash and category without exposing PII.
+    ** No key means no link/header; marketing must refuse rather than omit opt-out.
+    *******************************************************************************/
+   public static String create(String messageId, String recipient, String category)
+   {
+      if(!"NOTIFICATION".equals(category) && !"MARKETING".equals(category))
+      {
+         return (null);
+      }
+      String key;
+      try
+      {
+         key = EmailRuntime.config().getSecretResolver().apply("QQQ_EMAIL_UNSUBSCRIBE_KEY");
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Opt-out email needs publicBaseUrl and QQQ_EMAIL_UNSUBSCRIBE_KEY"));
+      }
+      String base = EmailRuntime.config().getPublicBaseUrl();
+      if(key == null || key.isBlank() || base == null || base.isBlank())
+      {
+         if("MARKETING".equals(category))
+         {
+            throw (new IllegalArgumentException("Opt-out email needs publicBaseUrl and QQQ_EMAIL_UNSUBSCRIBE_KEY"));
+         }
+         return (null);
+      }
+      String address = recipient(recipient, null, null);
+      try
+      {
+         VariableSchema.url(base);
+         String hash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(address.getBytes(StandardCharsets.UTF_8)));
+         String payload = Base64.getUrlEncoder().withoutPadding().encodeToString(VariableSchema.json(Map.of("messageId", messageId, "addressHash", hash, "category", category)).getBytes(StandardCharsets.UTF_8));
+         Mac mac = Mac.getInstance("HmacSHA256");
+         mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
+         String signed = "v1." + payload;
+         String signature = Base64.getUrlEncoder().withoutPadding().encodeToString(mac.doFinal(signed.getBytes(StandardCharsets.UTF_8)));
+         return (base.replaceAll("/+$", "") + EmailRuntime.config().getWebhookBasePath() + "/unsubscribe/" + signed + "." + signature);
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Opt-out email needs publicBaseUrl and QQQ_EMAIL_UNSUBSCRIBE_KEY"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Exactly one To mailbox, canonicalized for signing and category suppression.
+    *******************************************************************************/
+   public static String recipient(String to, String cc, String bcc)
+   {
+      try
+      {
+         InternetAddress[] addresses = InternetAddress.parse(to == null ? "" : to, true);
+         if(addresses.length == 1 && !addresses[0].isGroup() && addresses[0].getAddress().contains("@")
+            && (cc == null || cc.isBlank()) && (bcc == null || bcc.isBlank()))
+         {
+            addresses[0].validate();
+            return (addresses[0].getAddress().toLowerCase(Locale.ROOT));
+         }
+      }
+      catch(jakarta.mail.internet.AddressException e)
+      {
+         // Malformed stored envelopes cannot authorize an opt-out.
+      }
+      throw (new IllegalArgumentException("Notification and marketing email with an unsubscribe link goes to one recipient per message; send one message per recipient."));
+   }
+
+   /*******************************************************************************
+    ** Verify the signed format before any lookup or side effect.
+    ** Invalid and non-opt-out categories are indistinguishable to callers.
+    *******************************************************************************/
+   public static org.json.JSONObject verify(String token)
+   {
+      try
+      {
+         if(token == null || token.length() > 4096)
+         {
+            return (null);
+         }
+         String[] parts = token.split("\\.", -1);
+         String key = EmailRuntime.config().getSecretResolver().apply("QQQ_EMAIL_UNSUBSCRIBE_KEY");
+         if(parts.length != 3 || !"v1".equals(parts[0]) || key == null || key.isBlank())
+         {
+            return (null);
+         }
+         Mac mac = Mac.getInstance("HmacSHA256");
+         mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
+         if(!MessageDigest.isEqual(mac.doFinal((parts[0] + "." + parts[1]).getBytes(StandardCharsets.UTF_8)), Base64.getUrlDecoder().decode(parts[2])))
+         {
+            return (null);
+         }
+         var payload = new org.json.JSONObject(new String(Base64.getUrlDecoder().decode(parts[1]), StandardCharsets.UTF_8));
+         String category = payload.getString("category");
+         return (("MARKETING".equals(category) || "NOTIFICATION".equals(category)) ? payload : null);
+      }
+      catch(Exception e)
+      {
+         return (null);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/render/HtmlToText.java

@@ -0,0 +1,132 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.render;
+
+
+import javax.swing.text.MutableAttributeSet;
+import javax.swing.text.html.HTML;
+import javax.swing.text.html.HTMLEditorKit;
+import javax.swing.text.html.parser.ParserDelegator;
+import java.io.StringReader;
+
+
+/*******************************************************************************
+ ** HTML to readable text using the JDK parser (including entity decoding).
+ *******************************************************************************/
+public final class HtmlToText
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private HtmlToText()
+   {
+   }
+
+   /*******************************************************************************
+    ** Keep links, headings, lists and table rows; omit scripts and styles.
+    *******************************************************************************/
+   public static String convert(String html)
+   {
+      StringBuilder text = new StringBuilder();
+      try
+      {
+         new ParserDelegator().parse(new StringReader(html == null ? "" : html), new HTMLEditorKit.ParserCallback()
+         {
+            private int hidden;
+            private String href;
+
+            /*******************************************************************************
+             ** Start readable block boundaries and remember link destinations.
+             *******************************************************************************/
+            @Override
+            public void handleStartTag(HTML.Tag tag, MutableAttributeSet attributes, int position)
+            {
+               if(tag == HTML.Tag.STYLE || tag == HTML.Tag.SCRIPT || tag == HTML.Tag.HEAD)
+               {
+                  hidden++;
+               }
+               if(tag == HTML.Tag.A)
+               {
+                  href = (String) attributes.getAttribute(HTML.Attribute.HREF);
+               }
+               if(tag == HTML.Tag.LI)
+               {
+                  text.append("\n- ");
+               }
+               if(tag == HTML.Tag.TD || tag == HTML.Tag.TH)
+               {
+                  text.append(" ");
+               }
+            }
+
+            /*******************************************************************************
+             ** Add link destinations and block separators.
+             *******************************************************************************/
+            @Override
+            public void handleEndTag(HTML.Tag tag, int position)
+            {
+               if(tag == HTML.Tag.STYLE || tag == HTML.Tag.SCRIPT || tag == HTML.Tag.HEAD)
+               {
+                  hidden = Math.max(0, hidden - 1);
+               }
+               if(tag == HTML.Tag.A && href != null)
+               {
+                  text.append(" (").append(href).append(')');
+                  href = null;
+               }
+               if(tag.isBlock())
+               {
+                  text.append('\n');
+               }
+            }
+
+            /*******************************************************************************
+             ** Line breaks remain line breaks.
+             *******************************************************************************/
+            @Override
+            public void handleSimpleTag(HTML.Tag tag, MutableAttributeSet attributes, int position)
+            {
+               if(tag == HTML.Tag.BR)
+               {
+                  text.append('\n');
+               }
+            }
+
+            /*******************************************************************************
+             ** Parser-decoded text, excluding executable and metadata content.
+             *******************************************************************************/
+            @Override
+            public void handleText(char[] data, int position)
+            {
+               if(hidden == 0)
+               {
+                  text.append(data);
+               }
+            }
+         }, true);
+      }
+      catch(java.io.IOException e)
+      {
+         throw (new IllegalArgumentException("Could not convert email HTML"));
+      }
+      return (text.toString().replaceAll("[ \\t]+", " ").replaceAll(" *\\n *", "\n").replaceAll("\\n{3,}", "\n\n").strip());
+   }
+}

src/main/java/com/kingsrook/qbits/email/support/EmailApiMapper.java

@@ -0,0 +1,117 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.support;
+
+
+import com.kingsrook.qbits.email.api.EmailApiRequest;
+import com.kingsrook.qbits.email.api.EmailApiResult;
+import com.kingsrook.qbits.email.api.EmailApiStatus;
+import com.kingsrook.qbits.email.api.EmailApiTemplate;
+import com.kingsrook.qbits.email.outbox.EmailCategory;
+import com.kingsrook.qbits.email.outbox.EmailRequest;
+import com.kingsrook.qbits.email.outbox.EmailSendResult;
+import com.kingsrook.qbits.email.template.EmailTemplateDefinition;
+
+
+/*******************************************************************************
+ ** Internal adapter between the stable contract and the implementation.
+ *******************************************************************************/
+public final class EmailApiMapper
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailApiMapper()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Map every published request field without bypassing send validation.
+    *******************************************************************************/
+   public static EmailRequest request(EmailApiRequest request)
+   {
+      if(request == null)
+      {
+         return (null);
+      }
+      EmailRequest mapped = new EmailRequest()
+         .withTo(request.getTo())
+         .withCc(request.getCc())
+         .withBcc(request.getBcc())
+         .withFrom(request.getFrom())
+         .withFromAddressId(request.getFromAddressId())
+         .withReplyTo(request.getReplyTo())
+         .withSubject(request.getSubject())
+         .withMarkdownBody(request.getMarkdownBody())
+         .withHtmlBody(request.getHtmlBody())
+         .withTextBody(request.getTextBody())
+         .withProviderName(request.getProviderName())
+         .withTemplateName(request.getTemplateName())
+         .withBrandName(request.getBrandName())
+         .withLocale(request.getLocale())
+         .withIdempotencyKey(request.getIdempotencyKey())
+         .withTransaction(request.getTransaction(), request.getTransactionBackendName())
+         .withSendAfter(request.getSendAfter())
+         .withLinkedTableName(request.getLinkedTableName())
+         .withLinkedRecordId(request.getLinkedRecordId())
+         .withSenderQbit(request.getSenderQbit())
+         .withSenderProcess(request.getSenderProcess())
+         .withVariables(request.getVariables())
+         .withCategory(request.getCategory() == null ? null : EmailCategory.valueOf(request.getCategory().name()));
+      request.getRecordVariables().forEach((name, reference) -> mapped.withRecordVariable(name, reference.table(), reference.id()));
+      return (mapped);
+   }
+
+
+
+   /*******************************************************************************
+    ** Map the complete create-once template contract.
+    *******************************************************************************/
+   public static EmailTemplateDefinition template(EmailApiTemplate template)
+   {
+      EmailTemplateDefinition mapped = new EmailTemplateDefinition()
+         .withName(template.getName())
+         .withLabel(template.getLabel())
+         .withKind(template.getKind())
+         .withSubject(template.getSubject())
+         .withBody(template.getBody())
+         .withTextBody(template.getTextBody())
+         .withVariablesSchema(template.getVariablesSchema())
+         .withSampleVariables(template.getSampleVariables())
+         .withOwnerQbit(template.getOwnerQbit())
+         .withEditPermissionName(template.getEditPermissionName())
+         .withCategory(template.getCategory() == null ? null : EmailCategory.valueOf(template.getCategory().name()));
+      template.getVariables().forEach(variable -> mapped.withVariable(variable.name(), variable.label(), variable.type(), variable.required(), variable.classification()));
+      return (mapped);
+   }
+
+
+
+   /*******************************************************************************
+    ** Map enqueue outcomes by their stable names.
+    *******************************************************************************/
+   public static EmailApiResult result(EmailSendResult result)
+   {
+      return (new EmailApiResult(result.messageId(), EmailApiStatus.valueOf(result.status().name()), result.reasons()));
+   }
+}

src/main/java/com/kingsrook/qbits/email/support/SystemWrites.java

@@ -152,7 +152,7 @@ public final class SystemWrites
     *******************************************************************************/
    public static List<QRecord> query(String table, QQueryFilter filter) throws QException
    {
-      return (call(() -> new QueryAction().execute(new QueryInput(table).withFilter(filter)).getRecords()));
+      return (call(() -> new QueryAction().execute(new QueryInput(table).withShouldFetchHeavyFields(true).withShouldOmitHiddenFields(false).withFilter(filter)).getRecords()));
    }
 
 
@@ -162,7 +162,7 @@ public final class SystemWrites
     *******************************************************************************/
    public static List<QRecord> query(String table, QQueryFilter filter, QBackendTransaction transaction) throws QException
    {
-      return (call(() -> new QueryAction().execute(new QueryInput(table).withFilter(filter).withTransaction(transaction)).getRecords()));
+      return (call(() -> new QueryAction().execute(new QueryInput(table).withShouldFetchHeavyFields(true).withShouldOmitHiddenFields(false).withFilter(filter).withTransaction(transaction)).getRecords()));
    }
 
 

src/main/java/com/kingsrook/qbits/email/template/CliMjmlCompiler.java

@@ -0,0 +1,133 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+
+/*******************************************************************************
+ ** MJML stdin/stdout compiler with a total 20-second deadline and no files.
+ *******************************************************************************/
+public class CliMjmlCompiler implements MjmlCompilerInterface
+{
+   private final String binary;
+
+   /*******************************************************************************
+    ** Explicit executable path; no shell interpolation or PATH guessing.
+    *******************************************************************************/
+   public CliMjmlCompiler(String binary)
+   {
+      this.binary = binary;
+   }
+
+   /*******************************************************************************
+    ** Drain stdout concurrently with stdin, discarding potentially private stderr.
+    *******************************************************************************/
+   @Override
+   public String compile(String source)
+   {
+      rejectIncludes(source);
+      Process process = null;
+      try(var executor = Executors.newVirtualThreadPerTaskExecutor())
+      {
+         process = processBuilder().start();
+         Process running = process;
+         var task = executor.submit(() ->
+         {
+            var writer = executor.submit(() ->
+            {
+               try(var stdin = running.getOutputStream())
+               {
+                  stdin.write(source.getBytes(StandardCharsets.UTF_8));
+               }
+               return (null);
+            });
+            byte[] output = running.getInputStream().readNBytes(10_000_001);
+            if(output.length > 10_000_000)
+            {
+               throw (new IllegalArgumentException("MJML output too large"));
+            }
+            writer.get();
+            if(running.waitFor() != 0)
+            {
+               throw (new IllegalArgumentException("MJML compilation failed"));
+            }
+            return (new String(output, StandardCharsets.UTF_8));
+         });
+         try
+         {
+            return (task.get(20, TimeUnit.SECONDS));
+         }
+         finally
+         {
+            running.descendants().forEach(ProcessHandle::destroyForcibly);
+            running.destroyForcibly();
+            task.cancel(true);
+         }
+      }
+      catch(Exception e)
+      {
+         if(e instanceof InterruptedException)
+         {
+            Thread.currentThread().interrupt();
+         }
+         throw (new IllegalArgumentException("MJML compilation failed or exceeded 20 seconds"));
+      }
+      finally
+      {
+         if(process != null)
+         {
+            process.destroyForcibly();
+         }
+      }
+   }
+
+   /*******************************************************************************
+    ** MJML 4.x/5 supports allowIncludes=false. Refusing the source tag as well
+    ** removes include resolution and its dependence on the inherited directory.
+    *******************************************************************************/
+   public static void rejectIncludes(String source)
+   {
+      if(source != null && java.util.regex.Pattern.compile("(?i)<\\s*mj-include\\b").matcher(source).find())
+      {
+         throw (new IllegalArgumentException("MJML includes are not allowed"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Package seam for checking child isolation without executing a compiler.
+    *******************************************************************************/
+   ProcessBuilder processBuilder()
+   {
+      ProcessBuilder builder = new ProcessBuilder(binary, "-i", "-s", "--config.allowIncludes=false");
+      String path = builder.environment().get("PATH");
+      builder.environment().clear();
+      if(path != null)
+      {
+         builder.environment().put("PATH", path);
+      }
+      return (builder.redirectError(ProcessBuilder.Redirect.DISCARD));
+   }
+
+}

src/main/java/com/kingsrook/qbits/email/template/CrmLegacyTemplateRenderer.java

@@ -0,0 +1,90 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Compatibility for migrated CRM content. Customer values are never programs.
+ *******************************************************************************/
+public final class CrmLegacyTemplateRenderer
+{
+   private static final Pattern TOKENS = Pattern.compile("\\{\\{(contact.firstName|contact.lastName|company.name|owner.name|unsubscribeUrl)\\}\\}");
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmLegacyTemplateRenderer()
+   {
+   }
+
+   /*******************************************************************************
+    ** Preserve the original subject/body override and text-before-HTML behavior.
+    *******************************************************************************/
+   public static QRecord render(QRecord template, QRecord version, Map<String, Serializable> values, String subjectOverride, String bodyOverride)
+   {
+      if(!"crm".equals(template.getValueString("ownerQbit")) || Boolean.TRUE.equals(template.getValueBoolean("phiApproved")))
+      {
+         throw (new IllegalArgumentException("Legacy CRM content requires CRM ownership and cannot be PHI approved"));
+      }
+      String subject = subjectOverride == null || subjectOverride.isBlank() ? version.getValueString("subject") : subjectOverride;
+      String body = bodyOverride == null || bodyOverride.isBlank() ? version.getValueString("textSource") : bodyOverride;
+      if(body == null)
+      {
+         body = version.getValueString("bodySource");
+      }
+      if(subject == null || subject.isBlank() || body == null || body.isBlank())
+      {
+         throw (new IllegalArgumentException("Email subject and body are required"));
+      }
+      subject = replace(subject, values);
+      body = replace(body, values);
+      if(subject.contains("\r") || subject.contains("\n") || (long) subject.getBytes(StandardCharsets.UTF_8).length + body.getBytes(StandardCharsets.UTF_8).length > 1_048_576)
+      {
+         throw (new IllegalArgumentException("Invalid or oversized template output"));
+      }
+      return (new QRecord().withValue("subject", subject).withValue("markdownBody", body)
+         .withValue("templateId", template.getValue("id")).withValue("templateVersionId", version.getValue("id")));
+   }
+
+   /*******************************************************************************
+    ** Replace only tokens in the original source, retaining unknown literals.
+    *******************************************************************************/
+   private static String replace(String source, Map<String, Serializable> values)
+   {
+      Matcher matcher = TOKENS.matcher(source);
+      StringBuilder result = new StringBuilder();
+      while(matcher.find())
+      {
+         Serializable value = values.get(matcher.group(1));
+         matcher.appendReplacement(result, Matcher.quoteReplacement(value == null ? "" : value.toString()));
+      }
+      matcher.appendTail(result);
+      return (result.toString());
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailBuiltIns.java

@@ -0,0 +1,79 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.List;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Built-ins are created on first use, transactionally and without JVM state.
+ *******************************************************************************/
+public final class EmailBuiltIns
+{
+   public static final String OWNER = "qbit-email";
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailBuiltIns()
+   {
+   }
+
+   /*******************************************************************************
+    ** Seed the secure-link pattern. The unique template name arbitrates replicas.
+    *******************************************************************************/
+   public static void ensure() throws QException
+   {
+      if(!SystemWrites.query(EmailTables.TEMPLATE, EmailStore.equal("name", "email_secure_message")).isEmpty())
+      {
+         return;
+      }
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new InsertInput(EmailTables.TEMPLATE)))
+      {
+         QRecord template = SystemWrites.insert(EmailTables.TEMPLATE, List.of(new QRecord().withValue("name", "email_secure_message")
+            .withValue("label", "Secure message").withValue("kind", "MARKDOWN").withValue("category", "SECURITY").withValue("phiApproved", false).withValue("ownerQbit", OWNER)), tx).getRecords().getFirst();
+         if(template.getValue("id") == null || template.getErrors() != null && !template.getErrors().isEmpty())
+         {
+            tx.rollback();
+            return;
+         }
+         QRecord version = SystemWrites.insert(EmailTables.VERSION, List.of(new QRecord().withValue("templateId", template.getValue("id"))
+            .withValue("versionNumber", 1).withValue("status", "ACTIVE").withValue("locale", "en").withValue("subject", "New secure message")
+            .withValue("bodySource", "You have a new secure message from {{brand.label}}. Sign in to read it.\n\n[Read secure message]({{link}}){.button}")
+            .withValue("variablesSchema", "[{\"name\":\"link\",\"type\":\"URL\",\"required\":true}]")
+            .withValue("sampleVariables", "{\"link\":\"https://example.invalid/sign-in\"}")), tx).getRecords().getFirst();
+         if(version.getValue("id") == null || version.getErrors() != null && !version.getErrors().isEmpty())
+         {
+            throw (new QException("Could not install secure-message template"));
+         }
+         EmailStore.update(EmailTables.TEMPLATE, new QRecord().withValue("id", template.getValue("id")).withValue("activeVersionId", version.getValue("id")), tx);
+         tx.commit();
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailPreviewWidget.java

@@ -0,0 +1,130 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.List;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.outbox.EmailRequest;
+import com.kingsrook.qbits.email.render.ContrastCheck;
+import com.kingsrook.qbits.email.render.EmailBrands;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.RawHTML;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.jsoup.Jsoup;
+import org.jsoup.safety.Safelist;
+
+
+/*******************************************************************************
+ ** Inline preview fallback: Next strips iframes and style blocks. Samples are
+ ** sanitized server-side too; no live record references are read for previews.
+ *******************************************************************************/
+public class EmailPreviewWidget extends AbstractWidgetRenderer
+{
+   /*******************************************************************************
+    ** Fetch the version and parent as the viewer, then render sample data.
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      try
+      {
+         int id = Integer.parseInt(input.getQueryParams().get("id"));
+         List<QRecord> versions = new QueryAction().execute(new QueryInput(EmailTables.VERSION).withShouldFetchHeavyFields(true)
+            .withFilter(EmailStore.equal("id", id))).getRecords();
+         if(versions.isEmpty())
+         {
+            return (output("<p>Version unavailable.</p>"));
+         }
+         QRecord version = versions.getFirst();
+         List<QRecord> templates = new QueryAction().execute(new QueryInput(EmailTables.TEMPLATE)
+            .withFilter(EmailStore.equal("id", version.getValueInteger("templateId")))).getRecords();
+         if(templates.isEmpty())
+         {
+            return (output("<p>Template unavailable.</p>"));
+         }
+         QRecord template = templates.getFirst();
+         if("MJML".equals(template.getValueString("kind")) && version.getValueString("compiledHtml") == null)
+         {
+            if(!com.kingsrook.qbits.email.permissions.EmailPermissionChecker.has(com.kingsrook.qbits.email.permissions.EmailPermissions.MANAGE))
+            {
+               return (output("<p>Not compiled yet. Activate the version or use Preview as a manager.</p>"));
+            }
+            EmailVersions.validate(template, version);
+         }
+         EmailTemplateRenderer renderer = new EmailTemplateRenderer(template, version,
+            new EmailRequest().withVariables(VariableSchema.values(version.getValueString("sampleVariables"))));
+         QRecord rendered = renderer.render("preview", "https://example.invalid/unsubscribe/preview", false);
+         QRecord brand = EmailBrands.resolve(null, template);
+         String html = "<div style=\"min-width:0;overflow-wrap:anywhere\"><h3>" + EmailTemplateEngine.escape(rendered.getValueString("subject")) + "</h3>"
+            + "<p>Sample preview. Inline rendering; mail clients may display it differently.</p>"
+            + sample(rendered.getValueString("htmlBody"), brand, false, 390) + sample(rendered.getValueString("htmlBody"), brand, true, 600)
+            + "<h4>Plain text</h4><pre style=\"white-space:pre-wrap;overflow-wrap:anywhere;max-width:100%\">"
+            + EmailTemplateEngine.escape(rendered.getValueString("textBody")) + "</pre></div>";
+         return (output(html + "<p>" + EmailTemplateEngine.escape(String.join("; ", renderer.warnings())) + "</p>"));
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (output("<p>Preview unavailable: " + EmailTemplateEngine.escape(e.getMessage()) + "</p>"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Safe inline sample with bounded width and no executable source or CSS.
+    *******************************************************************************/
+   private static String sample(String html, QRecord brand, boolean dark, int width)
+   {
+      var document = Jsoup.parse(html);
+      document.select("head,script,style,iframe,form").remove();
+      document.select(".email-logo-" + (dark ? "light" : "dark")).remove();
+      String clean = Jsoup.clean(document.body().html(), Safelist.relaxed().addAttributes("td", "class"));
+      document = Jsoup.parseBodyFragment(clean);
+      document.select("table").forEach(e -> e.attr("style", "width:100%;table-layout:fixed;border-collapse:collapse"));
+      document.select("td,th").forEach(e -> e.attr("style", "overflow-wrap:anywhere;padding:6px"));
+      document.select("img").forEach(e -> e.attr("style", "max-width:100%;height:auto"));
+      document.select("pre").forEach(e -> e.attr("style", "white-space:pre-wrap;overflow-wrap:anywhere"));
+      document.select("a").forEach(e -> e.attr("style", "color:inherit;overflow-wrap:anywhere"));
+      document.select(".email-content").forEach(e -> e.attr("style", e.attr("style") + ";background-color:"
+         + ContrastCheck.color(brand, dark ? "darkBackgroundColor" : "backgroundColor") + ";color:"
+         + ContrastCheck.color(brand, dark ? "darkTextColor" : "textColor")));
+      document.select(".email-button").forEach(e -> e.attr("style", "padding:12px 20px;background-color:" + ContrastCheck.color(brand, dark ? "darkPrimaryColor" : "primaryColor")
+         + ";color:" + ContrastCheck.color(brand, dark ? "darkButtonTextColor" : "buttonTextColor") + "!important"));
+      document.select(".email-button a").forEach(e -> e.attr("style", "color:" + ContrastCheck.color(brand, dark ? "darkButtonTextColor" : "buttonTextColor") + "!important;display:block;overflow-wrap:anywhere"));
+      document.select("[class]").forEach(e -> e.removeAttr("class"));
+      return ("<h4>" + (dark ? "Dark" : "Light") + " · " + width + "px maximum</h4><div style=\"box-sizing:border-box;width:100%;max-width:"
+         + width + "px;padding:12px;overflow-wrap:anywhere;background-color:" + ContrastCheck.color(brand, dark ? "darkBackgroundColor" : "backgroundColor")
+         + ";color:" + ContrastCheck.color(brand, dark ? "darkTextColor" : "textColor") + "\">" + document.body().html() + "</div>");
+   }
+
+   /*******************************************************************************
+    ** Standard widget response.
+    *******************************************************************************/
+   private static RenderWidgetOutput output(String html)
+   {
+      return (new RenderWidgetOutput(new RawHTML(null, html)));
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailTemplateCustomizers.java

@@ -0,0 +1,172 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.render.EmailBrands;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.statusmessages.BadInputStatusMessage;
+
+
+/*******************************************************************************
+ ** Lifecycle and template edit permissions apply equally to forms and APIs.
+ *******************************************************************************/
+public class EmailTemplateCustomizers implements TableCustomizerInterface
+{
+   /*******************************************************************************
+    ** Merge sparse updates and protect stored lifecycle state, not caller claims.
+    *******************************************************************************/
+   @Override
+   public List<QRecord> preInsertOrUpdate(AbstractActionInput input, List<QRecord> rows, boolean preview, Optional<List<QRecord>> oldRecords) throws QException
+   {
+      if(SystemWrites.active())
+      {
+         return (rows);
+      }
+      for(QRecord row : rows)
+      {
+         QRecord old = oldRecords.orElse(List.of()).stream().filter(v -> Objects.equals(v.getValue("id"), row.getValue("id"))).findFirst().orElse(new QRecord());
+         QRecord merged = new QRecord();
+         merged.getValues().putAll(old.getValues());
+         merged.getValues().putAll(row.getValues());
+         try
+         {
+            String table = input instanceof com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput insert ? insert.getTableName()
+               : ((com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput) input).getTableName();
+            if(EmailTables.BRAND.equals(table))
+            {
+               EmailBrands.validate(merged);
+            }
+            else if(EmailTables.TEMPLATE.equals(table))
+            {
+               EmailVersions.requireEdit(old.getValue("id") == null ? merged : old, false);
+               protectedFields(row, old, List.of("phiApproved", "approvedVersionId", "phiApprovedBy", "phiApprovedDate", "activeVersionId"));
+               if(Boolean.TRUE.equals(old.getValueBoolean("phiApproved")))
+               {
+                  protectedFields(row, old, List.of("kind", "category", "brandId", "name"));
+               }
+            }
+            else
+            {
+               QRecord parent = EmailStore.get(EmailTables.TEMPLATE, merged.getValueInteger("templateId"), null);
+               if(parent == null)
+               {
+                  throw (new IllegalArgumentException("Template is required"));
+               }
+               EmailVersions.requireEdit(parent, false);
+               if(old.getValue("id") != null)
+               {
+                  protectedFields(row, old, List.of("templateId", "versionNumber", "status", "compiledHtml", "activatedDate"));
+                  immutable(old, parent);
+               }
+               else
+               {
+                  if(merged.getValueString("status") != null && !"DRAFT".equals(merged.getValueString("status")))
+                  {
+                     throw (new IllegalArgumentException("New versions must be DRAFT"));
+                  }
+                  row.setValue("status", "DRAFT");
+                  row.setValue("compiledHtml", null);
+               }
+               new VariableSchema(merged.getValueString("variablesSchema"));
+            }
+         }
+         catch(IllegalArgumentException e)
+         {
+            row.addError(new BadInputStatusMessage(e.getMessage()));
+         }
+      }
+      return (rows);
+   }
+
+   /*******************************************************************************
+    ** Lifecycle-owned fields cannot be changed through ordinary CRUD.
+    *******************************************************************************/
+   private static void protectedFields(QRecord row, QRecord old, List<String> fields)
+   {
+      for(String field : fields)
+      {
+         Object value = row.getValue(field);
+         if(row.getValues().containsKey(field) && !Objects.equals(value, old.getValue(field)) && !(old.getValue("id") == null && Boolean.FALSE.equals(value)))
+         {
+            throw (new IllegalArgumentException("Use the version actions to change " + field));
+         }
+      }
+   }
+
+   /*******************************************************************************
+    ** Approving a draft freezes its content, preventing approval substitution.
+    *******************************************************************************/
+   private static void immutable(QRecord version, QRecord template)
+   {
+      if(!"DRAFT".equals(version.getValueString("status")) || Objects.equals(version.getValue("id"), template.getValue("approvedVersionId")))
+      {
+         throw (new IllegalArgumentException("ACTIVE, RETIRED and PHI-approved versions cannot be edited; use New Version"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Preserve active/history rows and the same edit grants on deletion.
+    *******************************************************************************/
+   @Override
+   public List<QRecord> preDelete(DeleteInput input, List<QRecord> rows, boolean preview) throws QException
+   {
+      if(SystemWrites.active())
+      {
+         return (rows);
+      }
+      for(QRecord row : rows)
+      {
+         try
+         {
+            if(EmailTables.VERSION.equals(input.getTableName()))
+            {
+               QRecord parent = EmailStore.get(EmailTables.TEMPLATE, row.getValueInteger("templateId"), input.getTransaction());
+               EmailVersions.requireEdit(parent, false);
+               immutable(row, parent);
+            }
+            else if(EmailTables.TEMPLATE.equals(input.getTableName()))
+            {
+               EmailVersions.requireEdit(row, false);
+               if(!SystemWrites.query(EmailTables.VERSION, EmailStore.equal("templateId", row.getValueInteger("id")), input.getTransaction()).isEmpty())
+               {
+                  throw (new IllegalArgumentException("Templates with versions cannot be deleted"));
+               }
+            }
+         }
+         catch(IllegalArgumentException e)
+         {
+            row.addError(new BadInputStatusMessage(e.getMessage()));
+         }
+      }
+      return (rows);
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailTemplateDefinition.java

@@ -0,0 +1,315 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.email.outbox.EmailCategory;
+
+
+/*******************************************************************************
+ ** A template another qbit ships with its own code: its name, content and
+ ** variable contract. Hand it to {@link EmailTemplates#ensure} at startup or on
+ ** first use; it is created once as an ACTIVE version 1 and never overwritten.
+ *******************************************************************************/
+public final class EmailTemplateDefinition
+{
+   private String name;
+   private String label;
+   private EmailCategory category;
+   private String kind = "MARKDOWN";
+   private String subject;
+   private String body;
+   private String textBody;
+   private String variablesSchema;
+   private final List<Map<String, Object>> variables = new ArrayList<>();
+   private String sampleVariables;
+   private String ownerQbit;
+   private String editPermissionName;
+
+   /*******************************************************************************
+    ** Unique snake_case template name, as used by EmailRequest.withTemplateName.
+    *******************************************************************************/
+   public EmailTemplateDefinition withName(String name)
+   {
+      this.name = name;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Human label shown in the template table.
+    *******************************************************************************/
+   public EmailTemplateDefinition withLabel(String label)
+   {
+      this.label = label;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Template category; it decides opt-out and PHI rules.
+    *******************************************************************************/
+   public EmailTemplateDefinition withCategory(EmailCategory category)
+   {
+      this.category = category;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** MARKDOWN (the default), MJML or HTML.
+    *******************************************************************************/
+   public EmailTemplateDefinition withKind(String kind)
+   {
+      this.kind = kind;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Subject source, which may use variables.
+    *******************************************************************************/
+   public EmailTemplateDefinition withSubject(String subject)
+   {
+      this.subject = subject;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Body source in the template's kind.
+    *******************************************************************************/
+   public EmailTemplateDefinition withBody(String body)
+   {
+      this.body = body;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Optional plain-text source; omitted, it is derived from the body.
+    *******************************************************************************/
+   public EmailTemplateDefinition withTextBody(String textBody)
+   {
+      this.textBody = textBody;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** The variables schema as the JSON list the template table stores. Use this or
+    ** withVariable, not both.
+    *******************************************************************************/
+   public EmailTemplateDefinition withVariablesSchema(String variablesSchema)
+   {
+      this.variablesSchema = variablesSchema;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Declare one variable (type: STRING, NUMBER, DATE, DATE_TIME, BOOLEAN, URL,
+    ** LIST or RECORD; classification: PUBLIC, CONFIDENTIAL, PII, PHI or null).
+    *******************************************************************************/
+   public EmailTemplateDefinition withVariable(String name, String label, String type, boolean required, String classification)
+   {
+      Map<String, Object> entry = new LinkedHashMap<>();
+      entry.put("name", name);
+      entry.put("label", label);
+      entry.put("type", type);
+      entry.put("required", required);
+      entry.put("classification", classification);
+      variables.add(entry);
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Synthetic sample values as a JSON object, used to validate and preview.
+    *******************************************************************************/
+   public EmailTemplateDefinition withSampleVariables(String sampleVariables)
+   {
+      this.sampleVariables = sampleVariables;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** The qbit that owns this template.
+    *******************************************************************************/
+   public EmailTemplateDefinition withOwnerQbit(String ownerQbit)
+   {
+      this.ownerQbit = ownerQbit;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Optional permission, besides the email permission, needed to edit the template.
+    *******************************************************************************/
+   public EmailTemplateDefinition withEditPermissionName(String editPermissionName)
+   {
+      this.editPermissionName = editPermissionName;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** The template name.
+    *******************************************************************************/
+   public String getName()
+   {
+      return (name);
+   }
+
+   /*******************************************************************************
+    ** The template label.
+    *******************************************************************************/
+   public String getLabel()
+   {
+      return (label);
+   }
+
+   /*******************************************************************************
+    ** The template category.
+    *******************************************************************************/
+   public EmailCategory getCategory()
+   {
+      return (category);
+   }
+
+   /*******************************************************************************
+    ** The template kind.
+    *******************************************************************************/
+   public String getKind()
+   {
+      return (kind);
+   }
+
+   /*******************************************************************************
+    ** The subject source.
+    *******************************************************************************/
+   public String getSubject()
+   {
+      return (subject);
+   }
+
+   /*******************************************************************************
+    ** The body source.
+    *******************************************************************************/
+   public String getBody()
+   {
+      return (body);
+   }
+
+   /*******************************************************************************
+    ** The optional plain-text source.
+    *******************************************************************************/
+   public String getTextBody()
+   {
+      return (textBody);
+   }
+
+   /*******************************************************************************
+    ** The schema JSON: the explicit text, or the typed variables as a JSON list.
+    *******************************************************************************/
+   public String getVariablesSchema()
+   {
+      if(variablesSchema != null && !variablesSchema.isBlank())
+      {
+         return (variablesSchema);
+      }
+      return (VariableSchema.json(variables));
+   }
+
+   /*******************************************************************************
+    ** The sample values JSON, defaulting to an empty object.
+    *******************************************************************************/
+   public String getSampleVariables()
+   {
+      return (sampleVariables == null || sampleVariables.isBlank() ? "{}" : sampleVariables);
+   }
+
+   /*******************************************************************************
+    ** The owning qbit.
+    *******************************************************************************/
+   public String getOwnerQbit()
+   {
+      return (ownerQbit);
+   }
+
+   /*******************************************************************************
+    ** The optional edit permission.
+    *******************************************************************************/
+   public String getEditPermissionName()
+   {
+      return (editPermissionName);
+   }
+
+   /*******************************************************************************
+    ** Plain-language reasons the definition is incomplete or malformed, before any
+    ** rendering check. Empty when it passes.
+    *******************************************************************************/
+   public List<String> problems()
+   {
+      List<String> reasons = new ArrayList<>();
+      if(name == null || !name.matches("[a-z][a-z0-9_]{0,99}"))
+      {
+         reasons.add("Name must be snake_case: lowercase letters, digits and underscores, starting with a letter");
+      }
+      if(label == null || label.isBlank())
+      {
+         reasons.add("Label is required");
+      }
+      if(category == null)
+      {
+         reasons.add("Category is required");
+      }
+      if(kind == null || !List.of("MARKDOWN", "MJML", "HTML", "CRM_LEGACY").contains(kind))
+      {
+         reasons.add("Kind must be MARKDOWN, MJML, HTML or CRM_LEGACY");
+      }
+      if(subject == null || subject.isBlank())
+      {
+         reasons.add("Subject is required");
+      }
+      if(body == null || body.isBlank())
+      {
+         reasons.add("Body is required");
+      }
+      if(variablesSchema != null && !variablesSchema.isBlank() && !variables.isEmpty())
+      {
+         reasons.add("Declare variables with withVariablesSchema or withVariable, not both");
+      }
+      else
+      {
+         try
+         {
+            new VariableSchema(getVariablesSchema());
+         }
+         catch(IllegalArgumentException e)
+         {
+            reasons.add(e.getMessage());
+         }
+      }
+      try
+      {
+         VariableSchema.values(sampleVariables);
+      }
+      catch(IllegalArgumentException e)
+      {
+         reasons.add(e.getMessage());
+      }
+      return (reasons);
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailTemplateEngine.java

@@ -0,0 +1,418 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Deque;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+
+/*******************************************************************************
+ ** Small parsed template language: values, fallback, if and each, without code.
+ *******************************************************************************/
+public class EmailTemplateEngine
+{
+   private static final Pattern URL_ATTRIBUTE = Pattern.compile("(?i)(?:^|[\\s<])(href|src|action|background)\\s*=\\s*[\"']$");
+   private static final Pattern RENDERED_URL = Pattern.compile("(?is)\\b(href|src|action|background)(\\s*=\\s*)([\"'])(.*?)\\3");
+
+   /*******************************************************************************
+    ** One budget shared by all parts and nested blocks of a render.
+    *******************************************************************************/
+   public static class Budget
+   {
+      private int iterations;
+      private int bytes;
+
+      /*******************************************************************************
+       ** Count work before entering a loop body.
+       *******************************************************************************/
+      private void iterate()
+      {
+         if(++iterations > 10_000)
+         {
+            throw (new IllegalArgumentException("Template output is too large"));
+         }
+      }
+
+      /*******************************************************************************
+       ** Bound UTF-8 output before appending it.
+       *******************************************************************************/
+      private void append(StringBuilder out, String value)
+      {
+         if(value.length() > 1_048_576 || (bytes += value.getBytes(StandardCharsets.UTF_8).length) > 1_048_576)
+         {
+            throw (new IllegalArgumentException("Template output is too large"));
+         }
+         out.append(value);
+      }
+   }
+
+   /*******************************************************************************
+    ** Rendering context. Markdown uses entities for all punctuation so values
+    ** cannot inject Markdown links, images or block syntax.
+    *******************************************************************************/
+   public enum Context
+   {
+      HTML, TEXT, MARKDOWN
+   }
+
+   /*******************************************************************************
+    ** A parsed literal, expression or block.
+    *******************************************************************************/
+   private record Node(String kind, String value, String fallback, int line, List<Node> children, String attribute)
+   {
+   }
+
+   /*******************************************************************************
+    ** Validated immutable parse result.
+    *******************************************************************************/
+   public static class Parsed
+   {
+      private final List<Node> nodes;
+      private final Set<String> references;
+
+      /*******************************************************************************
+       ** Store parsed nodes.
+       *******************************************************************************/
+      private Parsed(List<Node> nodes, Set<String> references)
+      {
+         this.nodes = nodes;
+         this.references = Set.copyOf(references);
+      }
+
+      /*******************************************************************************
+       ** Render the already validated syntax tree.
+       *******************************************************************************/
+      public String render(Map<String, ?> values, Context context)
+      {
+         return (render(values, context, new Budget(), new ArrayList<>()));
+      }
+
+      /*******************************************************************************
+       ** Bindings referenced by values and block conditions, including nested blocks.
+       *******************************************************************************/
+      public Set<String> references()
+      {
+         return (references);
+      }
+
+      /*******************************************************************************
+       ** Render using the message-wide budget and safe author-facing warnings.
+       *******************************************************************************/
+      public String render(Map<String, ?> values, Context context, Budget budget, List<String> warnings)
+      {
+         StringBuilder out = new StringBuilder();
+         renderNodes(nodes, values, null, -1, context, budget, warnings, out);
+         return (context == Context.HTML ? validateRenderedUrls(out.toString(), warnings) : out.toString());
+      }
+
+   }
+
+   /*******************************************************************************
+    ** Parse once, checking balanced blocks and every variable, with line numbers.
+    *******************************************************************************/
+   public Parsed parse(String source, VariableSchema schema)
+   {
+      source = source == null ? "" : source;
+      List<Node> root = new ArrayList<>();
+      Deque<Node> stack = new ArrayDeque<>();
+      Set<String> references = new LinkedHashSet<>();
+      int position = 0;
+      int line = 1;
+      while(position < source.length())
+      {
+         List<Node> current = stack.isEmpty() ? root : stack.peek().children();
+         int start = source.indexOf("{{", position);
+         if(start < 0)
+         {
+            current.add(new Node("literal", source.substring(position), null, 0, List.of(), null));
+            break;
+         }
+         current.add(new Node("literal", source.substring(position, start), null, 0, List.of(), null));
+         for(int i = position; i < start; i++)
+         {
+            if(source.charAt(i) == '\n')
+            {
+               line++;
+            }
+         }
+         int end = source.indexOf("}}", start + 2);
+         if(end < 0)
+         {
+            throw (error(line, "Unclosed expression"));
+         }
+         String expression = source.substring(start + 2, end).trim();
+         if(expression.startsWith("/"))
+         {
+            if(stack.isEmpty() || !stack.peek().kind().equals(expression.substring(1)))
+            {
+               throw (error(line, "Block nesting error"));
+            }
+            stack.pop();
+         }
+         else
+         {
+            String kind = expression.startsWith("#if ") ? "if" : expression.startsWith("#each ") ? "each" : "value";
+            String binding = kind.equals("value") ? expression : expression.substring(kind.length() + 2).trim();
+            String[] parts = binding.split("\\|", 2);
+            String name = parts[0].trim();
+            boolean inEach = stack.stream().anyMatch(n -> n.kind().equals("each"));
+            boolean local = name.equals("this") || name.startsWith("this.") || name.equals("@index");
+            if(!name.matches("(?:[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*|@index)")
+               || (local ? !inEach : !schema.knows(name)) || !kind.equals("value") && parts.length > 1)
+            {
+               throw (error(line, "Unknown or unsupported variable " + name));
+            }
+            if(!local)
+            {
+               references.add(name);
+            }
+            var attribute = URL_ATTRIBUTE.matcher(source.substring(position, start));
+            Node node = new Node(kind, name, parts.length == 2 ? parts[1] : "", line, new ArrayList<>(), attribute.find() ? attribute.group(1).toLowerCase(java.util.Locale.ROOT) : null);
+            current.add(node);
+            if(!kind.equals("value"))
+            {
+               if(stack.size() >= 8)
+               {
+                  throw (error(line, "Blocks exceed 8 levels"));
+               }
+               stack.push(node);
+            }
+         }
+         for(int i = start; i < end + 2; i++)
+         {
+            if(source.charAt(i) == '\n')
+            {
+               line++;
+            }
+         }
+         position = end + 2;
+      }
+      if(!stack.isEmpty())
+      {
+         throw (error(stack.peek().line(), "Unclosed " + stack.peek().kind() + " block"));
+      }
+      return (new Parsed(root, references));
+   }
+
+   /*******************************************************************************
+    ** Render syntax nodes; loop scope is restored on every recursive return.
+    *******************************************************************************/
+   private static void renderNodes(List<Node> nodes, Map<String, ?> values, Object item, int index, Context context, Budget budget, List<String> warnings, StringBuilder out)
+   {
+      for(Node node : nodes)
+      {
+         Object value = node.value().equals("this") ? item : node.value().startsWith("this.") ? lookup(item, node.value().substring(5))
+            : node.value().equals("@index") ? index : lookup(values, node.value());
+         switch(node.kind())
+         {
+            case "literal" -> budget.append(out, node.value());
+            case "value" ->
+            {
+               String text = value == null || value.toString().isEmpty() ? node.fallback() : value.toString();
+               if(context == Context.HTML && node.attribute() != null && !text.isEmpty())
+               {
+                  try
+                  {
+                     VariableSchema.url(text, "href".equals(node.attribute()));
+                  }
+                  catch(IllegalArgumentException e)
+                  {
+                     text = "";
+                     String warning = "Unsafe URL omitted for " + node.value();
+                     if(!warnings.contains(warning))
+                     {
+                        warnings.add(warning);
+                     }
+                  }
+               }
+               if(text.length() > 1_048_576)
+               {
+                  throw (new IllegalArgumentException("Template output is too large"));
+               }
+               budget.append(out, encode(text, context));
+            }
+            case "if" ->
+            {
+               if(truthy(value))
+               {
+                  renderNodes(node.children(), values, item, index, context, budget, warnings, out);
+               }
+            }
+            case "each" ->
+            {
+               if(value instanceof List<?> list)
+               {
+                  for(int i = 0; i < list.size(); i++)
+                  {
+                     budget.iterate();
+                     renderNodes(node.children(), values, list.get(i), i, context, budget, warnings, out);
+                  }
+               }
+            }
+            default -> throw (new IllegalStateException("Invalid template node"));
+         }
+      }
+   }
+
+   /*******************************************************************************
+    ** Expressions in attributes require quotes, including after literal prefixes.
+    *******************************************************************************/
+   public static void validateHtml(String source)
+   {
+      boolean tag = false;
+      char quote = 0;
+      for(int i = 0; source != null && i < source.length(); i++)
+      {
+         char c = source.charAt(i);
+         if(tag && quote == 0 && source.startsWith("{{", i))
+         {
+            throw (new IllegalArgumentException("Template expressions in attributes must be quoted"));
+         }
+         if(quote != 0)
+         {
+            if(c == quote)
+            {
+               quote = 0;
+            }
+         }
+         else if(c == '<')
+         {
+            tag = true;
+         }
+         else if(c == '>')
+         {
+            tag = false;
+         }
+         else if(tag && (c == '\"' || c == '\''))
+         {
+            quote = c;
+         }
+      }
+   }
+
+   /*******************************************************************************
+    ** Recheck complete attributes after block expansion, so whitespace, split
+    ** values and conditional expressions cannot hide the URL context.
+    *******************************************************************************/
+   private static String validateRenderedUrls(String html, List<String> warnings)
+   {
+      var matcher = RENDERED_URL.matcher(html);
+      StringBuilder result = new StringBuilder();
+      while(matcher.find())
+      {
+         String value = org.jsoup.parser.Parser.unescapeEntities(matcher.group(4), true);
+         try
+         {
+            if(!value.isEmpty())
+            {
+               VariableSchema.url(value, "href".equalsIgnoreCase(matcher.group(1)));
+            }
+            matcher.appendReplacement(result, java.util.regex.Matcher.quoteReplacement(matcher.group()));
+         }
+         catch(IllegalArgumentException e)
+         {
+            String warning = "Unsafe " + matcher.group(1).toLowerCase(java.util.Locale.ROOT) + " URL omitted";
+            if(!warnings.contains(warning))
+            {
+               warnings.add(warning);
+            }
+            matcher.appendReplacement(result, java.util.regex.Matcher.quoteReplacement(matcher.group(1) + matcher.group(2) + matcher.group(3) + matcher.group(3)));
+         }
+      }
+      matcher.appendTail(result);
+      return (result.toString());
+   }
+
+   /*******************************************************************************
+    ** Dotted paths traverse maps only; no reflection, methods or arbitrary code.
+    *******************************************************************************/
+   public static Object lookup(Object values, String path)
+   {
+      if(values instanceof Map<?, ?> map)
+      {
+         if(map.containsKey(path))
+         {
+            return (map.get(path));
+         }
+         int dot = path.indexOf('.');
+         return (dot < 0 ? map.get(path) : lookup(map.get(path.substring(0, dot)), path.substring(dot + 1)));
+      }
+      return (null);
+   }
+
+   /*******************************************************************************
+    ** Explicit language truthiness.
+    *******************************************************************************/
+   public static boolean truthy(Object value)
+   {
+      if(value == null || Boolean.FALSE.equals(value) || value instanceof CharSequence s && s.isEmpty()
+         || value instanceof Collection<?> c && c.isEmpty() || value instanceof Map<?, ?> m && m.isEmpty())
+      {
+         return (false);
+      }
+      return (!(value instanceof Number n) || new BigDecimal(n.toString()).compareTo(BigDecimal.ZERO) != 0);
+   }
+
+   /*******************************************************************************
+    ** Escape values exactly once for the consuming grammar.
+    *******************************************************************************/
+   public static String encode(String value, Context context)
+   {
+      if(context == Context.TEXT)
+      {
+         return (value);
+      }
+      if(context == Context.MARKDOWN)
+      {
+         StringBuilder encoded = new StringBuilder();
+         value.codePoints().forEach(c -> encoded.append(Character.isLetterOrDigit(c) || c == ' ' ? new String(Character.toChars(c)) : "&#" + c + ";"));
+         return (encoded.toString());
+      }
+      return (escape(value));
+   }
+
+   /*******************************************************************************
+    ** Attribute and text escaping, including both quote types.
+    *******************************************************************************/
+   public static String escape(Object value)
+   {
+      return (value == null ? "" : value.toString().replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+         .replace("\"", "&quot;").replace("'", "&#39;"));
+   }
+
+   /*******************************************************************************
+    ** Stable author-facing parse diagnostic.
+    *******************************************************************************/
+   private static IllegalArgumentException error(int line, String message)
+   {
+      return (new IllegalArgumentException("Line " + line + ": " + message));
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailTemplateRenderer.java

@@ -0,0 +1,508 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.outbox.EmailCategory;
+import com.kingsrook.qbits.email.outbox.EmailRequest;
+import com.kingsrook.qbits.email.phi.EmailBodyEncryption;
+import com.kingsrook.qbits.email.phi.EmailClassifications;
+import com.kingsrook.qbits.email.phi.EmailClassifications.Level;
+import com.kingsrook.qbits.email.phi.EmailValueTokens;
+import com.kingsrook.qbits.email.render.EmailBrands;
+import com.kingsrook.qbits.email.render.EmailLayout;
+import com.kingsrook.qbits.email.render.EmailMarkdown;
+import com.kingsrook.qbits.email.render.HtmlToText;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Queue-time template resolution and rendering with sender-visible record data.
+ *******************************************************************************/
+public final class EmailTemplateRenderer
+{
+   private final EmailRequest request;
+   private final QRecord template;
+   private final QRecord version;
+   private final QRecord brand;
+   private final VariableSchema schema;
+   private final Map<String, Serializable> values;
+   private final Map<String, EmailRequest.RecordVariable> records;
+   private final EmailCategory category;
+   private final boolean approved;
+   private final List<String> warnings = new ArrayList<>();
+
+   /*******************************************************************************
+    ** Resolve a template's active locale, falling back only to English.
+    *******************************************************************************/
+   public static EmailTemplateRenderer prepare(EmailRequest request) throws QException
+   {
+      if("email_secure_message".equals(request.getTemplateName()))
+      {
+         EmailBuiltIns.ensure();
+      }
+      List<QRecord> templates = SystemWrites.query(EmailTables.TEMPLATE, EmailStore.equal("name", request.getTemplateName()));
+      if(templates.size() != 1)
+      {
+         throw (new IllegalArgumentException("Unknown email template"));
+      }
+      QRecord template = templates.getFirst();
+      List<QRecord> versions = SystemWrites.query(EmailTables.VERSION, EmailStore.equal("templateId", template.getValueInteger("id"))
+         .withCriteria(new QFilterCriteria("status", QCriteriaOperator.EQUALS, "ACTIVE")));
+      QRecord version = versions.stream().filter(v -> Objects.equals(request.getLocale(), v.getValueString("locale"))).findFirst()
+         .orElseGet(() -> versions.stream().filter(v -> "en".equals(v.getValueString("locale"))).findFirst().orElse(null));
+      if(version == null)
+      {
+         throw (new IllegalArgumentException("Template has no active version for this locale or en"));
+      }
+      return (new EmailTemplateRenderer(template, version, request));
+   }
+
+   /*******************************************************************************
+    ** Validate schema, provenance and all template syntax before any outbox write.
+    *******************************************************************************/
+   public EmailTemplateRenderer(QRecord template, QRecord version, EmailRequest request) throws QException
+   {
+      this.request = request;
+      this.template = template;
+      this.version = version;
+      approved = Boolean.TRUE.equals(template.getValueBoolean("phiApproved")) && version.getValue("id") != null
+         && Objects.equals(template.getValue("approvedVersionId"), version.getValue("id"));
+      brand = EmailBrands.resolve(approved ? null : request.getBrandName(), template);
+      if(approved)
+      {
+         for(String field : List.of("logoUrl", "logoDarkUrl"))
+         {
+            if(brand.getValueString(field) != null && !EmailBrands.allowedImage(brand.getValueString(field), brand))
+            {
+               brand.setValue(field, null);
+               warnings.add("Brand logo omitted: image host is not allowed");
+            }
+         }
+      }
+      EmailBrands.validate(brand);
+      schema = new VariableSchema(version.getValueString("variablesSchema"));
+      records = new LinkedHashMap<>(request.getRecordVariables());
+      if("CRM_LEGACY".equals(template.getValueString("kind")))
+      {
+         if(!records.isEmpty())
+         {
+            throw (new IllegalArgumentException("Legacy CRM variables must be supplied from caller-visible records"));
+         }
+         values = new LinkedHashMap<>(request.getVariables());
+         category = request.getCategory() == null ? EmailCategory.valueOf(template.getValueString("category")) : request.getCategory();
+         if(category != EmailCategory.TRANSACTIONAL && category != EmailCategory.MARKETING)
+         {
+            throw (new IllegalArgumentException("Legacy CRM templates support only transactional or marketing delivery"));
+         }
+         CrmLegacyTemplateRenderer.render(template, version, values, request.getSubject(), request.getMarkdownBody());
+         return;
+      }
+      java.util.Set<String> references = new java.util.LinkedHashSet<>();
+      for(String field : List.of("subject", "preheader", "bodySource", "textSource", "compiledHtml"))
+      {
+         references.addAll(new EmailTemplateEngine().parse(version.getValueString(field), schema).references());
+      }
+      if(!"MARKDOWN".equals(template.getValueString("kind")))
+      {
+         EmailTemplateEngine.validateHtml(version.getValueString("bodySource"));
+         EmailTemplateEngine.validateHtml(version.getValueString("compiledHtml"));
+      }
+      Map<String, Serializable> supplied = new LinkedHashMap<>(request.getVariables());
+      for(var binding : records.entrySet())
+      {
+         supplied.keySet().removeIf(key -> key.startsWith(binding.getKey() + "."));
+         QTableMetaData table = QContext.getQInstance().getTable(binding.getValue().table());
+         if(table == null)
+         {
+            throw (new IllegalArgumentException("Record variable table is unavailable"));
+         }
+         java.util.Set<String> fields = references.stream().filter(path -> path.startsWith(binding.getKey() + "."))
+            .map(path -> path.substring(binding.getKey().length() + 1).split("\\.")[0]).collect(java.util.stream.Collectors.toSet());
+         if(fields.isEmpty())
+         {
+            supplied.put(binding.getKey(), new LinkedHashMap<>());
+            continue;
+         }
+         // Never use SystemWrites here: masking and record locks belong to the sender.
+         List<QRecord> rows = new QueryAction().execute(new QueryInput(table.getName()).withShouldFetchHeavyFields(true).withFieldNamesToInclude(fields)
+            .withFilter(EmailStore.equal(table.getPrimaryKeyField(), binding.getValue().id()).withLimit(1))).getRecords();
+         if(rows.isEmpty())
+         {
+            throw (new IllegalArgumentException("Record variable is unavailable to the sender"));
+         }
+         Map<String, Serializable> visible = new LinkedHashMap<>();
+         fields.forEach(field -> visible.put(field, rows.getFirst().getValue(field)));
+         for(var field : table.getFields().values())
+         {
+            var lock = field.getFieldSecurityLock();
+            if(lock != null && fields.contains(field.getName()))
+            {
+               var session = QContext.getQSession();
+               List<Serializable> keys = session == null ? List.of() : session.getSecurityKeyValues(lock.getSecurityKeyType());
+               boolean override = keys != null && lock.getOverrideValues() != null && keys.stream().anyMatch(lock.getOverrideValues()::contains);
+               boolean allowed = lock.getDefaultBehavior() == com.kingsrook.qqq.backend.core.model.metadata.security.FieldSecurityLock.Behavior.ALLOW;
+               if(override ? allowed : !allowed)
+               {
+                  visible.put(field.getName(), "************");
+               }
+            }
+         }
+         supplied.put(binding.getKey(), new LinkedHashMap<>(visible));
+      }
+      for(String name : supplied.keySet())
+      {
+         if(!schema.knows(name) || name.startsWith("brand.") || name.equals("message.id") || name.equals("now") || name.equals("unsubscribe_url"))
+         {
+            throw (new IllegalArgumentException("Unknown or reserved input variable " + name));
+         }
+      }
+      values = schema.validate(supplied);
+      category = EmailCategory.valueOf(Objects.requireNonNullElse(template.getValueString("category"), "TRANSACTIONAL"));
+      if(request.getCategory() != null && request.getCategory() != category)
+      {
+         throw (new IllegalArgumentException("Template category cannot be overridden"));
+      }
+      if(approved && category == EmailCategory.MARKETING)
+      {
+         throw (new IllegalArgumentException("PHI-approved templates cannot send MARKETING email"));
+      }
+      for(VariableSchema.Entry entry : schema.entries().values())
+      {
+         requireApproval(entry.name(), classification(entry.name()));
+      }
+      inspect(values, "");
+      for(String field : List.of("subject", "preheader", "bodySource", "textSource"))
+      {
+         new EmailTemplateEngine().parse(version.getValueString(field), schema);
+      }
+      if(version.getValueString("subject") == null || version.getValueString("bodySource") == null)
+      {
+         throw (new IllegalArgumentException("A template subject and body are required"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Check actual nested fields as well as declared but absent bindings.
+    *******************************************************************************/
+   private void inspect(Object object, String path)
+   {
+      if(!path.isEmpty())
+      {
+         requireApproval(path, classification(path));
+      }
+      if(object instanceof Map<?, ?> map)
+      {
+         map.forEach((key, value) -> inspect(value, path.isEmpty() ? key.toString() : path + "." + key));
+      }
+      else if(object instanceof List<?> list)
+      {
+         list.forEach(value -> inspect(value, path));
+      }
+   }
+
+   /*******************************************************************************
+    ** A classification failure names only the binding, never its value.
+    *******************************************************************************/
+   private void requireApproval(String name, Level level)
+   {
+      if(EmailClassifications.sensitive(level) && !approved)
+      {
+         throw (new IllegalArgumentException("The variable " + name + " is " + level + "; this template is not approved for PHI."));
+      }
+   }
+
+   /*******************************************************************************
+    ** Resolve record provenance before schema declarations; inherit parent levels.
+    *******************************************************************************/
+   private Level classification(String path)
+   {
+      VariableSchema.Entry declaration = schema.entries().get(path);
+      if(declaration == null)
+      {
+         declaration = schema.entries().values().stream().filter(e -> path.startsWith(e.name() + "."))
+            .max(java.util.Comparator.comparingInt(e -> e.name().length())).orElse(null);
+      }
+      String declared = declaration == null ? null : declaration.classification();
+      for(var record : records.entrySet())
+      {
+         if(path.startsWith(record.getKey() + "."))
+         {
+            String field = path.substring(record.getKey().length() + 1).split("\\.")[0];
+            return (EmailClassifications.ofField(QContext.getQInstance().getTable(record.getValue().table()), field, declared, EmailRuntime.config()));
+         }
+      }
+      QTableMetaData table = declaration == null || declaration.table() == null ? null : QContext.getQInstance().getTable(declaration.table());
+      if(declaration != null && declaration.table() != null && (table == null || table.getField(declaration.field()) == null))
+      {
+         throw (new IllegalArgumentException("Schema field binding is unavailable"));
+      }
+      return (EmailClassifications.ofField(table, declaration == null ? null : declaration.field(), declared, EmailRuntime.config()));
+   }
+
+   /*******************************************************************************
+    ** Validate the actual provider at queue and delivery time.
+    *******************************************************************************/
+   public void validateProvider(QRecord provider)
+   {
+      if(approved)
+      {
+         checkProvider(provider);
+      }
+   }
+
+   /*******************************************************************************
+    ** Recheck mutable provider attestations before encrypted content leaves storage.
+    *******************************************************************************/
+   public static void checkProvider(QRecord provider)
+   {
+      if(!Boolean.TRUE.equals(provider.getValueBoolean("phiAllowed")) || Boolean.TRUE.equals(provider.getValueBoolean("trackOpens"))
+         || Boolean.TRUE.equals(provider.getValueBoolean("trackClicks")))
+      {
+         throw (new IllegalArgumentException("PHI email needs a phi_allowed provider with open and click tracking disabled"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Render with the real message identity; no compiled source is rebuilt at send.
+    *******************************************************************************/
+   public QRecord render(String messageId, String unsubscribe, boolean encrypt)
+   {
+      return (render(messageId, unsubscribe, encrypt, true));
+   }
+
+   /*******************************************************************************
+    ** Render typed content for an existing transport, which adds its own layout.
+    *******************************************************************************/
+   public QRecord renderContent(String messageId, String unsubscribe)
+   {
+      return (render(messageId, unsubscribe, false, false));
+   }
+
+   /*******************************************************************************
+    ** Share parsing, classification and output limits across both consumers.
+    *******************************************************************************/
+   private QRecord render(String messageId, String unsubscribe, boolean encrypt, boolean decorate)
+   {
+      if("CRM_LEGACY".equals(template.getValueString("kind")))
+      {
+         QRecord rendered = CrmLegacyTemplateRenderer.render(template, version, values, request.getSubject(), request.getMarkdownBody());
+         String html = EmailMarkdown.render(rendered.getValueString("markdownBody"), brand);
+         if(decorate)
+         {
+            html = EmailLayout.render(html, null, brand, category, unsubscribe);
+         }
+         String text = HtmlToText.convert(html);
+         if((long) rendered.getValueString("subject").getBytes(java.nio.charset.StandardCharsets.UTF_8).length
+            + html.getBytes(java.nio.charset.StandardCharsets.UTF_8).length + text.getBytes(java.nio.charset.StandardCharsets.UTF_8).length > 1_048_576)
+         {
+            throw (new IllegalArgumentException("Template output is too large"));
+         }
+         return (rendered.withValue("htmlBody", html).withValue("textBody", text)
+            .withValue("variablesSnapshot", "{}").withValue("brandId", brand.getValue("id"))
+            .withValue("locale", version.getValue("locale")).withValue("category", category.name()).withValue("phiApproved", false));
+      }
+      Map<String, Serializable> context = new LinkedHashMap<>(values);
+      for(String field : List.of("label", "name", "siteUrl", "logoUrl", "logoDarkUrl", "logoAlt", "postalAddress", "primaryColor", "textColor", "backgroundColor", "darkBackgroundColor", "darkTextColor", "buttonTextColor", "darkPrimaryColor", "darkButtonTextColor", "footerMarkdown"))
+      {
+         context.put("brand." + field.replaceAll("([a-z])([A-Z])", "$1_$2").toLowerCase(java.util.Locale.ROOT), brand.getValueString(field));
+      }
+      context.put("message.id", messageId);
+      context.put("now", EmailRuntime.clock().instant().toString());
+      context.put("unsubscribe_url", category == EmailCategory.NOTIFICATION || category == EmailCategory.MARKETING ? unsubscribe : "");
+      EmailTemplateEngine engine = new EmailTemplateEngine();
+      EmailTemplateEngine.Budget budget = new EmailTemplateEngine.Budget();
+      String subject = engine.parse(version.getValueString("subject"), schema).render(context, EmailTemplateEngine.Context.TEXT, budget, warnings);
+      if(subject.contains("\r") || subject.contains("\n"))
+      {
+         throw (new IllegalArgumentException("Subject must be one line"));
+      }
+      String kind = template.getValueString("kind");
+      String source = "MJML".equals(kind) ? version.getValueString("compiledHtml") : version.getValueString("bodySource");
+      if(source == null)
+      {
+         throw (new IllegalArgumentException("MJML version must be compiled before sending"));
+      }
+      String body = engine.parse(source, schema).render(context, "MARKDOWN".equals(kind) ? EmailTemplateEngine.Context.MARKDOWN : EmailTemplateEngine.Context.HTML, budget, warnings);
+      String preheader = engine.parse(version.getValueString("preheader"), schema).render(context, EmailTemplateEngine.Context.TEXT, budget, warnings);
+      String html = "MARKDOWN".equals(kind) ? EmailMarkdown.render(body, brand) : body;
+      if(decorate)
+      {
+         html = "MARKDOWN".equals(kind) ? EmailLayout.render(html, preheader, brand, category, unsubscribe)
+            : EmailLayout.appendFooter(html, brand, category, unsubscribe);
+      }
+      if(approved)
+      {
+         html = restrictImages(html);
+      }
+      String text = version.getValueString("textSource") == null ? HtmlToText.convert(html)
+         : engine.parse(version.getValueString("textSource"), schema).render(context, EmailTemplateEngine.Context.TEXT, budget, warnings);
+      if((long) subject.getBytes(java.nio.charset.StandardCharsets.UTF_8).length + html.getBytes(java.nio.charset.StandardCharsets.UTF_8).length
+         + text.getBytes(java.nio.charset.StandardCharsets.UTF_8).length > 1_048_576)
+      {
+         throw (new IllegalArgumentException("Template output is too large"));
+      }
+      return (new QRecord().withValue("subject", approved && encrypt ? EmailBodyEncryption.encrypt(subject, "subject", messageId) : subject)
+         .withValue("htmlBody", approved && encrypt ? EmailBodyEncryption.encrypt(html, "htmlBody", messageId) : html)
+         .withValue("textBody", approved && encrypt ? EmailBodyEncryption.encrypt(text, "textBody", messageId) : text)
+         .withValue("variablesSnapshot", VariableSchema.json(snapshot(values, "", messageId)))
+         .withValue("templateId", template.getValue("id")).withValue("templateVersionId", version.getValue("id"))
+         .withValue("brandId", brand.getValue("id")).withValue("locale", version.getValue("locale"))
+         .withValue("category", category.name()).withValue("phiApproved", approved));
+   }
+
+   /*******************************************************************************
+    ** Recursive redaction prevents nested records or lists bypassing tokenization.
+    *******************************************************************************/
+   private Object snapshot(Object value, String path, String messageId)
+   {
+      if(!path.isEmpty() && (EmailClassifications.sensitive(classification(path)) || unclassifiedRecordField(path)))
+      {
+         for(var record : records.entrySet())
+         {
+            if(path.startsWith(record.getKey() + ".") && !path.substring(record.getKey().length() + 1).contains("."))
+            {
+               QTableMetaData table = QContext.getQInstance().getTable(record.getValue().table());
+               var field = table.getField(path.substring(record.getKey().length() + 1));
+               if(field != null)
+               {
+                  return (EmailValueTokens.forRecordField(table, field, record.getValue().id(), (Serializable) value));
+               }
+            }
+         }
+         return (EmailValueTokens.forContext(List.of("email", template.getValueString("name"), path, messageId), (Serializable) value));
+      }
+      if(value instanceof Map<?, ?> map)
+      {
+         Map<String, Object> result = new LinkedHashMap<>();
+         map.forEach((key, item) -> result.put(key.toString(), snapshot(item, path.isEmpty() ? key.toString() : path + "." + key, messageId)));
+         return (result);
+      }
+      if(value instanceof List<?> list)
+      {
+         List<Object> result = new ArrayList<>();
+         list.forEach(item -> result.add(snapshot(item, path, messageId)));
+         return (result);
+      }
+      return (value == null || value instanceof Number || value instanceof Boolean ? value : value.toString());
+   }
+
+   /*******************************************************************************
+    ** Missing record classification fails closed only in the retained snapshot.
+    *******************************************************************************/
+   private boolean unclassifiedRecordField(String path)
+   {
+      for(var record : records.entrySet())
+      {
+         if(path.startsWith(record.getKey() + "."))
+         {
+            String field = path.substring(record.getKey().length() + 1).split("\\.")[0];
+            return (!EmailClassifications.hasSource(QContext.getQInstance().getTable(record.getValue().table()), field, EmailRuntime.config()));
+         }
+      }
+      return (false);
+   }
+
+   /*******************************************************************************
+    ** Warnings contain binding names and policy reasons, never input values.
+    *******************************************************************************/
+   public List<String> warnings()
+   {
+      return (List.copyOf(new java.util.LinkedHashSet<>(warnings)));
+   }
+
+   /*******************************************************************************
+    ** Apply the image policy after Markdown, layout and brand footer expansion.
+    *******************************************************************************/
+   private String restrictImages(String html)
+   {
+      var document = org.jsoup.Jsoup.parse(html);
+      document.outputSettings().prettyPrint(false);
+      document.select("[src],[background],[srcset],image").forEach(element ->
+      {
+         element.removeAttr("srcset");
+         if(element.hasAttr("src") && !EmailBrands.allowedImage(element.attr("src"), brand))
+         {
+            element.remove();
+            warnings.add("Image omitted: image host is not allowed");
+         }
+         if(element.hasAttr("background") && !EmailBrands.allowedImage(element.attr("background"), brand))
+         {
+            element.removeAttr("background");
+            warnings.add("Image omitted: image host is not allowed");
+         }
+         if("image".equals(element.normalName()))
+         {
+            element.remove();
+            warnings.add("SVG image omitted from approved email");
+         }
+      });
+      org.jsoup.select.NodeTraversor.filter((node, depth) ->
+      {
+         if(node instanceof org.jsoup.nodes.Comment comment && comment.getData().toLowerCase(java.util.Locale.ROOT).contains("[if"))
+         {
+            warnings.add("Conditional markup omitted from approved email");
+            return (org.jsoup.select.NodeFilter.FilterResult.REMOVE);
+         }
+         return (org.jsoup.select.NodeFilter.FilterResult.CONTINUE);
+      }, document);
+      // CSS image expressions can use escapes and image-set, so approved content
+      // uses img elements instead of CSS images. Layout colors remain intact.
+      document.select("[style]").forEach(element ->
+      {
+         String style = element.attr("style");
+         if(style.toLowerCase(java.util.Locale.ROOT).contains("url") || style.contains("\\") || style.toLowerCase(java.util.Locale.ROOT).contains("image-set"))
+         {
+            element.removeAttr("style");
+            warnings.add("CSS image omitted from approved email");
+         }
+      });
+      document.select("style").forEach(element ->
+      {
+         String style = element.data();
+         if(style.toLowerCase(java.util.Locale.ROOT).contains("url") || style.contains("\\") || style.toLowerCase(java.util.Locale.ROOT).contains("@import") || style.toLowerCase(java.util.Locale.ROOT).contains("image-set"))
+         {
+            element.remove();
+            warnings.add("CSS image omitted from approved email");
+         }
+      });
+      return (document.outerHtml());
+   }
+
+}

src/main/java/com/kingsrook/qbits/email/template/EmailTemplates.java

@@ -0,0 +1,118 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.List;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Entry point for other qbits to ship their templates. A template is created
+ ** once; after that this class never touches it, so people's edits are safe.
+ *******************************************************************************/
+public final class EmailTemplates
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailTemplates()
+   {
+   }
+
+   /*******************************************************************************
+    ** Create the template and an ACTIVE version 1 when no template of that name
+    ** exists. The definition is validated like Activate Version (syntax, schema, a
+    ** render with the samples, MJML compile); an invalid one is refused with
+    ** plain reasons and nothing is written. Returns true only when this call
+    ** created the template; the unique name arbitrates concurrent callers.
+    *******************************************************************************/
+   public static boolean ensure(EmailTemplateDefinition definition) throws QException
+   {
+      List<String> reasons = definition.problems();
+      if(!reasons.isEmpty())
+      {
+         throw (new IllegalArgumentException("Template definition refused: " + String.join("; ", reasons)));
+      }
+      return (SystemWrites.call(() -> create(definition)));
+   }
+
+   /*******************************************************************************
+    ** The checked, transactional creation, run as the qbit.
+    *******************************************************************************/
+   private static boolean create(EmailTemplateDefinition definition) throws QException
+   {
+      if(exists(definition.getName()))
+      {
+         return (false);
+      }
+      QRecord template = new QRecord().withValue("name", definition.getName()).withValue("label", definition.getLabel())
+         .withValue("category", definition.getCategory().name()).withValue("kind", definition.getKind()).withValue("phiApproved", false)
+         .withValue("ownerQbit", definition.getOwnerQbit()).withValue("editPermissionName", definition.getEditPermissionName());
+      QRecord version = new QRecord().withValue("versionNumber", 1).withValue("status", "ACTIVE").withValue("locale", "en")
+         .withValue("subject", definition.getSubject()).withValue("bodySource", definition.getBody()).withValue("textSource", definition.getTextBody())
+         .withValue("variablesSchema", definition.getVariablesSchema()).withValue("sampleVariables", definition.getSampleVariables());
+      try
+      {
+         EmailVersions.validate(template, version);
+      }
+      catch(IllegalArgumentException e)
+      {
+         throw (new IllegalArgumentException("Template definition refused: " + e.getMessage()));
+      }
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new InsertInput(EmailTables.TEMPLATE)))
+      {
+         QRecord stored = SystemWrites.insert(EmailTables.TEMPLATE, List.of(template), tx).getRecords().getFirst();
+         if(stored.getValue("id") == null || stored.getErrors() != null && !stored.getErrors().isEmpty())
+         {
+            tx.rollback();
+            if(exists(definition.getName()))
+            {
+               return (false);
+            }
+            throw (new QException("Could not create template " + definition.getName()));
+         }
+         version.withValue("templateId", stored.getValue("id"));
+         QRecord storedVersion = SystemWrites.insert(EmailTables.VERSION, List.of(version), tx).getRecords().getFirst();
+         if(storedVersion.getValue("id") == null || storedVersion.getErrors() != null && !storedVersion.getErrors().isEmpty())
+         {
+            throw (new QException("Could not create template version for " + definition.getName()));
+         }
+         EmailStore.update(EmailTables.TEMPLATE, new QRecord().withValue("id", stored.getValue("id")).withValue("activeVersionId", storedVersion.getValue("id")), tx);
+         tx.commit();
+         return (true);
+      }
+   }
+
+   /*******************************************************************************
+    ** Whether a template of that name is already present.
+    *******************************************************************************/
+   private static boolean exists(String name) throws QException
+   {
+      return (!SystemWrites.query(EmailTables.TEMPLATE, EmailStore.equal("name", name)).isEmpty());
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailVersionLabels.java

@@ -0,0 +1,68 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Human-readable version labels, resolving parent names as the current viewer.
+ *******************************************************************************/
+public class EmailVersionLabels implements TableCustomizerInterface
+{
+   /*******************************************************************************
+    ** Batch parents to avoid one query per version, without bypassing security.
+    *******************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface input, List<QRecord> records) throws QException
+   {
+      var ids = records.stream().map(r -> r.getValueInteger("templateId")).filter(Objects::nonNull).distinct().toList();
+      Map<Integer, String> names = new HashMap<>();
+      if(!ids.isEmpty())
+      {
+         List<QRecord> templates = new QueryAction().execute(new QueryInput(EmailTables.TEMPLATE)
+            .withFilter(new QQueryFilter().withCriteria("id", QCriteriaOperator.IN, ids))
+            .withFieldNamesToInclude(new HashSet<>(List.of("id", "name")))).getRecords();
+         templates.forEach(t -> names.put(t.getValueInteger("id"), t.getValueString("name")));
+      }
+      for(QRecord row : records)
+      {
+         String locale = row.getValueString("locale");
+         row.setRecordLabel(names.getOrDefault(row.getValueInteger("templateId"), "Template") + " v" + row.getValueInteger("versionNumber")
+            + (locale == null || locale.isBlank() || "en".equals(locale) ? "" : " (" + locale + ")"));
+      }
+      return (records);
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/EmailVersions.java

@@ -0,0 +1,221 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.util.List;
+import java.util.Objects;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.outbox.EmailRequest;
+import com.kingsrook.qbits.email.permissions.EmailPermissionChecker;
+import com.kingsrook.qbits.email.permissions.EmailPermissions;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Atomic version lifecycle. Approval binds to exactly one immutable version.
+ *******************************************************************************/
+public final class EmailVersions
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailVersions()
+   {
+   }
+
+   /*******************************************************************************
+    ** Enforce both the qbit permission and the template's independent edit grant.
+    *******************************************************************************/
+   public static void requireEdit(QRecord template, boolean approval)
+   {
+      if(SystemWrites.active())
+      {
+         return;
+      }
+      if(!EmailPermissionChecker.has(approval ? EmailPermissions.ADMIN : EmailPermissions.MANAGE)
+         && (approval || !EmailPermissionChecker.hasTemplatePermission(true)))
+      {
+         throw (new IllegalArgumentException(approval ? "PHI approval needs email.admin" : "Editing templates needs email.manage"));
+      }
+      String permission = template.getValueString("editPermissionName");
+      if(permission != null && !permission.isBlank() && (QContext.getQSession() == null || !QContext.getQSession().hasPermission(permission)))
+      {
+         throw (new IllegalArgumentException("Editing this template needs " + permission));
+      }
+   }
+
+   /*******************************************************************************
+    ** Serialize lifecycle operations across replicas using the template row.
+    *******************************************************************************/
+   private static QRecord lock(Integer templateId, QBackendTransaction tx) throws QException
+   {
+      QRecord template = EmailStore.get(EmailTables.TEMPLATE, templateId, tx);
+      if(template == null)
+      {
+         throw (new IllegalArgumentException("Template not found"));
+      }
+      requireEdit(template, false);
+      EmailStore.update(EmailTables.TEMPLATE, new QRecord().withValue("id", templateId).withValue("versionLock", 0), tx);
+      return (EmailStore.get(EmailTables.TEMPLATE, templateId, tx));
+   }
+
+   /*******************************************************************************
+    ** Copy active (or latest) into a new draft, with a globally increasing number.
+    *******************************************************************************/
+   public static QRecord newVersion(Integer templateId) throws QException
+   {
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.TEMPLATE)))
+      {
+         QRecord template = lock(templateId, tx);
+         List<QRecord> versions = SystemWrites.query(EmailTables.VERSION, EmailStore.equal("templateId", templateId)
+            .withOrderBy(new QFilterOrderBy("versionNumber", false)), tx);
+         QRecord source = versions.stream().filter(v -> Objects.equals(template.getValue("activeVersionId"), v.getValue("id"))).findFirst()
+            .orElse(versions.isEmpty() ? new QRecord().withValue("locale", "en").withValue("variablesSchema", "[]").withValue("sampleVariables", "{}") : versions.getFirst());
+         QRecord draft = new QRecord();
+         for(String field : List.of("locale", "subject", "preheader", "bodySource", "textSource", "variablesSchema", "sampleVariables"))
+         {
+            draft.setValue(field, source.getValue(field));
+         }
+         draft.withValue("templateId", templateId).withValue("versionNumber", versions.isEmpty() ? 1 : versions.getFirst().getValueInteger("versionNumber") + 1)
+            .withValue("status", "DRAFT").withValue("createdBy", actor());
+         QRecord result = SystemWrites.insert(EmailTables.VERSION, List.of(draft), tx).getRecords().getFirst();
+         if(result.getValue("id") == null || result.getErrors() != null && !result.getErrors().isEmpty())
+         {
+            throw (new QException("Could not create template version"));
+         }
+         tx.commit();
+         return (result);
+      }
+   }
+
+   /*******************************************************************************
+    ** Approval is granted to the selected draft or active version, never retired.
+    *******************************************************************************/
+   public static void approve(Integer versionId) throws QException
+   {
+      QRecord version = requiredVersion(versionId, null);
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.TEMPLATE)))
+      {
+         QRecord template = lock(version.getValueInteger("templateId"), tx);
+         requireEdit(template, true);
+         version = requiredVersion(versionId, tx);
+         if("CRM_LEGACY".equals(template.getValueString("kind")) || "RETIRED".equals(version.getValueString("status")) || "MARKETING".equals(template.getValueString("category")))
+         {
+            throw (new IllegalArgumentException("Legacy CRM templates, retired versions and MARKETING templates cannot be approved for PHI"));
+         }
+         EmailStore.update(EmailTables.TEMPLATE, new QRecord().withValue("id", template.getValue("id"))
+            .withValue("phiApproved", true).withValue("approvedVersionId", versionId).withValue("phiApprovedBy", actor())
+            .withValue("phiApprovedDate", EmailRuntime.clock().instant()), tx);
+         tx.commit();
+      }
+   }
+
+   /*******************************************************************************
+    ** Validate samples and syntax, compile MJML, then atomically retire and activate.
+    *******************************************************************************/
+   public static void activate(Integer versionId) throws QException
+   {
+      QRecord initial = requiredVersion(versionId, null);
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.TEMPLATE)))
+      {
+         QRecord template = lock(initial.getValueInteger("templateId"), tx);
+         QRecord version = requiredVersion(versionId, tx);
+         if(!"DRAFT".equals(version.getValueString("status")))
+         {
+            throw (new IllegalArgumentException("Only a DRAFT version can be activated"));
+         }
+         validate(template, version);
+         for(QRecord previous : SystemWrites.query(EmailTables.VERSION, EmailStore.equal("templateId", template.getValueInteger("id")), tx))
+         {
+            if("ACTIVE".equals(previous.getValueString("status")) && Objects.equals(version.getValue("locale"), previous.getValue("locale")))
+            {
+               EmailStore.update(EmailTables.VERSION, new QRecord().withValue("id", previous.getValue("id")).withValue("status", "RETIRED"), tx);
+            }
+         }
+         EmailStore.update(EmailTables.VERSION, new QRecord().withValue("id", versionId).withValue("status", "ACTIVE")
+            .withValue("compiledHtml", version.getValue("compiledHtml")).withValue("activatedDate", EmailRuntime.clock().instant()), tx);
+         QRecord change = new QRecord().withValue("id", template.getValue("id")).withValue("activeVersionId", versionId);
+         if(!Objects.equals(template.getValue("approvedVersionId"), versionId))
+         {
+            change.withValue("phiApproved", false).withValue("approvedVersionId", null).withValue("phiApprovedBy", null).withValue("phiApprovedDate", null);
+         }
+         EmailStore.update(EmailTables.TEMPLATE, change, tx);
+         tx.commit();
+      }
+   }
+
+   /*******************************************************************************
+    ** Review validation is side-effect-free; compiled output stays in memory.
+    *******************************************************************************/
+   public static void validate(QRecord template, QRecord version) throws QException
+   {
+      requireEdit(template, false);
+      if("CRM_LEGACY".equals(template.getValueString("kind")))
+      {
+         CrmLegacyTemplateRenderer.render(template, version, java.util.Map.of(), null, null);
+         return;
+      }
+      if("MJML".equals(template.getValueString("kind")))
+      {
+         CliMjmlCompiler.rejectIncludes(version.getValueString("bodySource"));
+         EmailTemplateEngine.validateHtml(version.getValueString("bodySource"));
+         if(EmailRuntime.config().getMjmlCompiler() == null)
+         {
+            throw (new IllegalArgumentException("MJML activation needs a configured compiler"));
+         }
+         new EmailTemplateEngine().parse(version.getValueString("bodySource"), new VariableSchema(version.getValueString("variablesSchema")));
+         version.setValue("compiledHtml", EmailRuntime.config().getMjmlCompiler().compile(version.getValueString("bodySource")));
+      }
+      EmailTemplateRenderer renderer = new EmailTemplateRenderer(template, version,
+         new EmailRequest().withVariables(VariableSchema.values(version.getValueString("sampleVariables"))));
+      renderer.render("preview", "https://example.invalid/unsubscribe/preview", false);
+   }
+
+   /*******************************************************************************
+    ** Load a required version without exposing database diagnostics.
+    *******************************************************************************/
+   public static QRecord requiredVersion(Integer id, QBackendTransaction tx) throws QException
+   {
+      QRecord version = EmailStore.get(EmailTables.VERSION, id, tx);
+      if(version == null)
+      {
+         throw (new IllegalArgumentException("Template version not found"));
+      }
+      return (version);
+   }
+
+   /*******************************************************************************
+    ** Stable session actor identity, with an explicit system fallback.
+    *******************************************************************************/
+   private static String actor()
+   {
+      return (QContext.getQSession() == null || QContext.getQSession().getUser() == null ? "system" : QContext.getQSession().getUser().getIdReference());
+   }
+}

src/main/java/com/kingsrook/qbits/email/template/MjmlCompilerInterface.java

@@ -0,0 +1,34 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+/*******************************************************************************
+ ** Activation-time compilation only. Implementations must not persist sources.
+ *******************************************************************************/
+@FunctionalInterface
+public interface MjmlCompilerInterface
+{
+   /*******************************************************************************
+    ** Return HTML or a content-free failure.
+    *******************************************************************************/
+   String compile(String source);
+}

src/main/java/com/kingsrook/qbits/email/template/VariableSchema.java

@@ -0,0 +1,212 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.template;
+
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.net.URI;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+
+/*******************************************************************************
+ ** Declarative variable contract. Validation errors never include input values.
+ *******************************************************************************/
+public class VariableSchema
+{
+   private final Map<String, Entry> entries = new LinkedHashMap<>();
+   private static final ObjectMapper JSON = new ObjectMapper();
+
+   /*******************************************************************************
+    ** One schema binding, including optional record provenance.
+    *******************************************************************************/
+   public record Entry(String name, String label, String type, boolean required, String classification, String table, String field)
+   {
+   }
+
+   /*******************************************************************************
+    ** Parse the JSON list and reject ambiguous or unsupported declarations.
+    *******************************************************************************/
+   public VariableSchema(String json)
+   {
+      try
+      {
+         List<Entry> parsed = JSON.readValue(json == null || json.isBlank() ? "[]" : json, new TypeReference<List<Entry>>() {});
+         for(Entry entry : parsed)
+         {
+            if(entry.name() == null || !entry.name().matches("[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*")
+               || !List.of("STRING", "NUMBER", "DATE", "DATE_TIME", "BOOLEAN", "URL", "LIST", "RECORD").contains(entry.type())
+               || entries.putIfAbsent(entry.name(), entry) != null
+               || entry.classification() != null && !List.of("PUBLIC", "CONFIDENTIAL", "PII", "PHI").contains(entry.classification())
+               || (entry.table() == null) != (entry.field() == null))
+            {
+               throw (new IllegalArgumentException());
+            }
+         }
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Invalid variables schema"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Declared bindings in stable order.
+    *******************************************************************************/
+   public Map<String, Entry> entries()
+   {
+      return (Map.copyOf(entries));
+   }
+
+   /*******************************************************************************
+    ** Built-ins and paths under declared records are known to the parser.
+    *******************************************************************************/
+   public boolean knows(String name)
+   {
+      if(name.equals("now") || name.equals("message.id") || name.equals("unsubscribe_url")
+         || name.matches("brand\\.(label|name|site_url|logo_url|logo_dark_url|logo_alt|postal_address|primary_color|text_color|background_color|dark_background_color|dark_text_color|button_text_color|dark_primary_color|dark_button_text_color|footer_markdown)"))
+      {
+         return (true);
+      }
+      return (entries.containsKey(name) || entries.values().stream().anyMatch(e ->
+         ("RECORD".equals(e.type()) || "LIST".equals(e.type())) && name.startsWith(e.name() + ".")));
+   }
+
+   /*******************************************************************************
+    ** Validate and coerce declared values without discarding record structure.
+    *******************************************************************************/
+   public Map<String, Serializable> validate(Map<String, Serializable> values)
+   {
+      Map<String, Serializable> result = new LinkedHashMap<>(values);
+      for(Entry entry : entries.values())
+      {
+         Object value = EmailTemplateEngine.lookup(values, entry.name());
+         if(value == null || value instanceof String s && s.isEmpty())
+         {
+            if(entry.required())
+            {
+               throw (new IllegalArgumentException("Required variable " + entry.name() + " is missing"));
+            }
+            continue;
+         }
+         try
+         {
+            Serializable coerced = switch(entry.type())
+            {
+               case "STRING" -> value.toString();
+               case "NUMBER" -> new BigDecimal(value.toString());
+               case "DATE" -> LocalDate.parse(value.toString());
+               case "DATE_TIME" -> Instant.parse(value.toString());
+               case "BOOLEAN" -> booleanValue(value);
+               case "URL" -> url(value.toString());
+               case "LIST" -> (Serializable) (List<?>) value;
+               case "RECORD" -> (Serializable) (Map<?, ?>) value;
+               default -> throw (new IllegalArgumentException());
+            };
+            result.put(entry.name(), coerced);
+         }
+         catch(Exception e)
+         {
+            throw (new IllegalArgumentException("Variable " + entry.name() + " must be " + entry.type()));
+         }
+      }
+      return (result);
+   }
+
+   /*******************************************************************************
+    ** Strict boolean coercion avoids silently turning misspellings into false.
+    *******************************************************************************/
+   private static Boolean booleanValue(Object value)
+   {
+      if(!List.of("true", "false").contains(value.toString().toLowerCase(java.util.Locale.ROOT)))
+      {
+         throw (new IllegalArgumentException());
+      }
+      return (Boolean.valueOf(value.toString()));
+   }
+
+   /*******************************************************************************
+    ** Only absolute web URLs are allowed in variable and brand URL fields.
+    *******************************************************************************/
+   public static String url(String value)
+   {
+      return (url(value, false));
+   }
+
+   /*******************************************************************************
+    ** The same URL policy, optionally allowing mailto only for link destinations.
+    *******************************************************************************/
+   public static String url(String value, boolean allowMailto)
+   {
+      URI uri = URI.create(value);
+      if(allowMailto && "mailto".equalsIgnoreCase(uri.getScheme()) && !uri.getRawSchemeSpecificPart().isBlank()
+         && !value.matches("(?is).*%(?:0a|0d).*"))
+      {
+         return (value);
+      }
+      if(uri.getScheme() == null || !List.of("http", "https").contains(uri.getScheme().toLowerCase(java.util.Locale.ROOT)) || uri.getHost() == null || uri.getUserInfo() != null)
+      {
+         throw (new IllegalArgumentException("URL must use http or https"));
+      }
+      return (value);
+   }
+
+   /*******************************************************************************
+    ** Parse process inputs and sample values; never echo malformed JSON.
+    *******************************************************************************/
+   public static Map<String, Serializable> values(String json)
+   {
+      try
+      {
+         Map<String, Serializable> result = JSON.readValue(json == null || json.isBlank() ? "{}" : json, new TypeReference<LinkedHashMap<String, Serializable>>() {});
+         if(result == null)
+         {
+            throw (new IllegalArgumentException());
+         }
+         return (result);
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Variables must be a JSON object"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Serialize safe snapshots using the existing Jackson dependency.
+    *******************************************************************************/
+   public static String json(Object value)
+   {
+      try
+      {
+         return (JSON.writeValueAsString(value));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Could not serialize email variables"));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/EmailEventParser.java

@@ -0,0 +1,302 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Provider payloads become small recipient-level events, never message bodies.
+ *******************************************************************************/
+public final class EmailEventParser
+{
+   /*******************************************************************************
+    ** Provider identifiers remain scoped to the provider during database matching.
+    *******************************************************************************/
+   public record Event(String externalId, String messageId, String providerMessageId, String type, String bounceType,
+      String recipient, Instant occurred, String detail, String url)
+   {
+   }
+
+   /*******************************************************************************
+    ** Parse one provider request, including all SendGrid events and SES recipients.
+    *******************************************************************************/
+   public List<Event> parse(String kind, String body, Instant received)
+   {
+      List<Event> events = new ArrayList<>();
+      switch(kind)
+      {
+         case "SES" -> ses(new JSONObject(body), received, events);
+         case "POSTMARK" -> postmark(new JSONObject(body), received, events);
+         case "MAILGUN" -> mailgun(new JSONObject(body).getJSONObject("event-data"), received, events);
+         case "SENDGRID" ->
+         {
+            JSONArray batch = new JSONArray(body);
+            for(int i = 0; i < batch.length(); i++)
+            {
+               sendgrid(batch.getJSONObject(i), received, events);
+            }
+         }
+         default -> throw new IllegalArgumentException("Unsupported email event kind");
+      }
+      return (events);
+   }
+
+   /*******************************************************************************
+    ** SES recipients live under the specific event, with mail.destination fallback for non-suppressive events only.
+    *******************************************************************************/
+   private static void ses(JSONObject envelope, Instant received, List<Event> events)
+   {
+      if(!"Notification".equals(envelope.getString("Type")))
+      {
+         return;
+      }
+      JSONObject payload = new JSONObject(envelope.getString("Message"));
+      String rawType = payload.optString("eventType", payload.optString("notificationType"));
+      String type = switch(rawType)
+      {
+         case "Delivery" -> "DELIVERED";
+         case "Bounce" -> "BOUNCED";
+         case "Complaint" -> "COMPLAINED";
+         case "Reject" -> "REJECTED";
+         case "DeliveryDelay" -> "DEFERRED";
+         case "Open" -> "OPENED";
+         case "Click" -> "CLICKED";
+         default -> null;
+      };
+      if(type == null)
+      {
+         return;
+      }
+      JSONObject mail = payload.getJSONObject("mail");
+      String key = "DeliveryDelay".equals(rawType) ? "deliveryDelay" : rawType.toLowerCase(Locale.ROOT);
+      JSONObject data = object(payload, key);
+      String bounce = "BOUNCED".equals(type) ? switch(data.optString("bounceType"))
+      {
+         case "Permanent" -> "HARD";
+         case "Transient" -> "SOFT";
+         default -> "UNDETERMINED";
+      } : null;
+      String messageId = null;
+      JSONArray headers = mail.optJSONArray("headers");
+      if(headers != null)
+      {
+         for(int i = 0; i < headers.length(); i++)
+         {
+            JSONObject entry = headers.getJSONObject(i);
+            if("X-QQQ-Email-Id".equalsIgnoreCase(entry.optString("name")))
+            {
+               messageId = entry.optString("value", null);
+            }
+         }
+      }
+      JSONArray recipients = data.optJSONArray(switch(type)
+      {
+         case "BOUNCED" -> "bouncedRecipients";
+         case "COMPLAINED" -> "complainedRecipients";
+         case "DEFERRED" -> "delayedRecipients";
+         default -> "recipients";
+      });
+      if(recipients == null && ("BOUNCED".equals(type) || "COMPLAINED".equals(type)))
+      {
+         // Never widen a bounce or complaint to every destination; the event carries no recipient and is skipped.
+         events.add(new Event(envelope.getString("MessageId"), messageId, mail.getString("messageId"), type, bounce, null,
+            time(data.opt("timestamp"), received), null, null));
+         return;
+      }
+      if(recipients == null)
+      {
+         recipients = mail.getJSONArray("destination");
+      }
+      for(int i = 0; i < recipients.length(); i++)
+      {
+         Object recipient = recipients.get(i);
+         String address = recipient instanceof JSONObject row ? row.getString("emailAddress") : recipient.toString();
+         String reason = recipient instanceof JSONObject row ? row.optString("diagnosticCode", data.optString("bounceSubType", null))
+            : data.optString("reason", data.optString("smtpResponse", data.optString("delayType", data.optString("complaintFeedbackType", null))));
+         events.add(new Event(envelope.getString("MessageId"), messageId, mail.getString("messageId"), type, bounce, address,
+            time(data.opt("timestamp"), received), detail(reason), "CLICKED".equals(type) ? data.optString("link", null) : null));
+      }
+   }
+
+   /*******************************************************************************
+    ** Postmark subscription reactivation is informational, never an unsubscribe.
+    *******************************************************************************/
+   private static void postmark(JSONObject data, Instant received, List<Event> events)
+   {
+      String type = switch(data.getString("RecordType"))
+      {
+         case "Delivery" -> "DELIVERED";
+         case "Bounce" -> "BOUNCED";
+         case "SpamComplaint" -> "COMPLAINED";
+         case "Open" -> "OPENED";
+         case "Click" -> "CLICKED";
+         case "SubscriptionChange" -> data.optBoolean("SuppressSending", false) ? "UNSUBSCRIBED" : null;
+         default -> null;
+      };
+      if(type == null)
+      {
+         return;
+      }
+      String bounce = "BOUNCED".equals(type) ? switch(data.optString("Type"))
+      {
+         case "HardBounce", "SpamNotification", "SpamComplaint", "BadEmailAddress", "ManuallyDeactivated" -> "HARD";
+         case "SoftBounce", "Transient", "DnsError", "MailboxFull" -> "SOFT";
+         default -> "UNDETERMINED";
+      } : null;
+      Object date = data.opt("DeliveredAt");
+      for(String field : List.of("BouncedAt", "ReceivedAt", "ChangedAt"))
+      {
+         if(data.has(field))
+         {
+            date = data.get(field);
+         }
+      }
+      String id = data.has("ID") ? data.get("RecordType") + ":" + data.get("ID") : fingerprint(data);
+      events.add(new Event(id, null, data.optString("MessageID", null), type, bounce,
+         data.optString("Recipient", data.optString("Email", null)), time(date, received),
+         detail(data.optString("Description", data.optString("Details", data.optString("SuppressionReason", null)))),
+         "CLICKED".equals(type) ? data.optString("OriginalLink", null) : null));
+   }
+
+   /*******************************************************************************
+    ** SendGrid retains the provider message id prefix before its delivery suffix.
+    *******************************************************************************/
+   private static void sendgrid(JSONObject data, Instant received, List<Event> events)
+   {
+      String type = switch(data.getString("event"))
+      {
+         case "delivered" -> "DELIVERED";
+         case "bounce" -> "BOUNCED";
+         case "dropped" -> "REJECTED";
+         case "deferred" -> "DEFERRED";
+         case "spamreport" -> "COMPLAINED";
+         case "open" -> "OPENED";
+         case "click" -> "CLICKED";
+         case "unsubscribe", "group_unsubscribe" -> "UNSUBSCRIBED";
+         default -> null;
+      };
+      if(type == null)
+      {
+         return;
+      }
+      String bounce = "BOUNCED".equals(type) ? ("blocked".equals(data.optString("type")) ? "SOFT" : "HARD") : null;
+      String providerMessage = data.optString("sg_message_id", null);
+      if(providerMessage != null && providerMessage.contains("."))
+      {
+         providerMessage = providerMessage.substring(0, providerMessage.indexOf('.'));
+      }
+      events.add(new Event(data.optString("sg_event_id", fingerprint(data)),
+         data.optString("qqq_email_id", object(data, "custom_args").optString("qqq_email_id", null)), providerMessage, type, bounce,
+         data.optString("email", null), time(data.opt("timestamp"), received), detail(data.optString("reason", data.optString("response", null))),
+         "CLICKED".equals(type) ? data.optString("url", null) : null));
+   }
+
+   /*******************************************************************************
+    ** Mailgun MIME ids are normalized identically to the outbound transport.
+    *******************************************************************************/
+   private static void mailgun(JSONObject data, Instant received, List<Event> events)
+   {
+      String type = switch(data.getString("event"))
+      {
+         case "delivered" -> "DELIVERED";
+         case "failed" -> "BOUNCED";
+         case "complained" -> "COMPLAINED";
+         case "opened" -> "OPENED";
+         case "clicked" -> "CLICKED";
+         case "unsubscribed" -> "UNSUBSCRIBED";
+         default -> null;
+      };
+      if(type == null)
+      {
+         return;
+      }
+      String bounce = "BOUNCED".equals(type) ? switch(data.optString("severity"))
+      {
+         case "permanent" -> "HARD";
+         case "temporary" -> "SOFT";
+         default -> "UNDETERMINED";
+      } : null;
+      JSONObject variables = object(data, "user-variables");
+      String providerMessage = object(object(data, "message"), "headers").optString("message-id", null);
+      if(providerMessage != null)
+      {
+         providerMessage = providerMessage.replaceAll("^<|>$", "");
+      }
+      events.add(new Event(data.optString("id", fingerprint(data)), variables.optString("qqq_email_id", variables.optString("v:qqq_email_id", null)),
+         providerMessage, type, bounce, data.optString("recipient", null), time(data.opt("timestamp"), received),
+         detail(data.optString("reason", object(data, "delivery-status").optString("message", null))), "CLICKED".equals(type) ? data.optString("url", null) : null));
+   }
+
+   /*******************************************************************************
+    ** Optional nested objects contain no executable data.
+    *******************************************************************************/
+   private static JSONObject object(JSONObject parent, String key)
+   {
+      JSONObject value = parent.optJSONObject(key);
+      return (value == null ? new JSONObject() : value);
+   }
+
+   /*******************************************************************************
+    ** Fall back to receipt time only when the provider supplied no timestamp.
+    *******************************************************************************/
+   private static Instant time(Object value, Instant fallback)
+   {
+      if(value == null || JSONObject.NULL.equals(value))
+      {
+         return (fallback);
+      }
+      if(value instanceof Number number)
+      {
+         return (Instant.ofEpochMilli((long) (number.doubleValue() * 1000)));
+      }
+      return (OffsetDateTime.parse(value.toString()).toInstant());
+   }
+
+   /*******************************************************************************
+    ** Fallback identity for providers without a distinct event identifier.
+    *******************************************************************************/
+   private static String fingerprint(JSONObject data)
+   {
+      return (WebhookVerification.hash(data.toString().getBytes(StandardCharsets.UTF_8)));
+   }
+
+   /*******************************************************************************
+    ** Mask complete addresses before truncation, including quoted local parts.
+    *******************************************************************************/
+   public static String detail(String reason)
+   {
+      if(reason == null)
+      {
+         return (null);
+      }
+      String masked = reason.replaceAll("(?i)(?:\"[^\"]*\"|[^\\s<>(),;:]+)@[^\\s<>(),;:]+", "[address]");
+      return (masked.substring(0, Math.min(500, masked.length())));
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/EmailInboxProcessor.java

@@ -0,0 +1,333 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Objects;
+import java.util.Set;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.delivery.EmailAlerts;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import jakarta.mail.internet.InternetAddress;
+
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Bounded, replica-safe database transactions apply inbox rows exactly once.
+ ** No network or external effects occur while the row's provider is locked.
+ *******************************************************************************/
+public final class EmailInboxProcessor
+{
+   private static final QLogger LOG = QLogger.getLogger(EmailInboxProcessor.class);
+
+   private static final int MAX_ATTEMPTS = 6;
+
+   /*******************************************************************************
+    ** Poll due rows; transaction rollback releases claims after a worker crash.
+    *******************************************************************************/
+   public int runOnce() throws QException
+   {
+      int processed = 0;
+      for(QRecord row : SystemWrites.query(EmailTables.INBOX, EmailStore.equal("status", "PENDING")
+         .withCriteria("nextAttemptDate", QCriteriaOperator.LESS_THAN_OR_EQUALS, EmailRuntime.clock().instant())
+         .withOrderBy(new QFilterOrderBy("id")).withLimit(EmailRuntime.config().getBatchSize())))
+      {
+         if(process(row))
+         {
+            processed++;
+         }
+      }
+      return (processed);
+   }
+
+   /*******************************************************************************
+    ** Re-read eligibility after the lock, including the observed attempt number.
+    *******************************************************************************/
+   private static boolean due(QRecord current, QRecord observed)
+   {
+      return (current != null && "PENDING".equals(current.getValueString("status"))
+         && Objects.equals(current.getValue("attempts"), observed.getValue("attempts"))
+         && current.getValueInstant("nextAttemptDate") != null && !current.getValueInstant("nextAttemptDate").isAfter(EmailRuntime.clock().instant()));
+   }
+
+   /*******************************************************************************
+    ** All event, message, suppression and receipt changes commit together.
+    *******************************************************************************/
+   private boolean process(QRecord observed) throws QException
+   {
+      boolean complaint = false;
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.PROVIDER)))
+      {
+         QRecord provider = EmailTrackingStore.lock(observed.getValueInteger("providerId"), tx);
+         QRecord row = EmailStore.get(EmailTables.INBOX, observed.getValueInteger("id"), tx);
+         if(!due(row, observed))
+         {
+            return (false);
+         }
+         int applied = 0;
+         int unmatched = 0;
+         int skipped = 0;
+         for(EmailEventParser.Event event : new EmailEventParser().parse(row.getValueString("kind"), row.getValueString("payloadJson"), row.getValueInstant("receivedDate")))
+         {
+            if(("OPENED".equals(event.type()) && !Boolean.TRUE.equals(provider.getValueBoolean("trackOpens")))
+               || ("CLICKED".equals(event.type()) && !Boolean.TRUE.equals(provider.getValueBoolean("trackClicks"))))
+            {
+               continue;
+            }
+            QRecord message = match(event, provider.getValueInteger("id"), tx);
+            if(message == null || "SENDING".equals(message.getValueString("status")))
+            {
+               unmatched++;
+               continue;
+            }
+            String recipient = normalize(event.recipient());
+            if(recipient == null || !recipients(message).contains(recipient))
+            {
+               LOG.info("Ignoring an email event whose recipient is not on the message", logPair("messageId", message.getValue("id")));
+               skipped++;
+               continue;
+            }
+            if(Boolean.TRUE.equals(message.getValueBoolean("phiApproved")) && List.of("OPENED", "CLICKED").contains(event.type()))
+            {
+               continue;
+            }
+            String key = provider.getValueInteger("id") + ":" + WebhookVerification.hash((event.externalId() + "\n" + event.type() + "\n"
+               + recipient).getBytes(StandardCharsets.UTF_8));
+            QRecord stored = EmailTrackingStore.event(message, event, key, tx);
+            if(stored == null)
+            {
+               continue;
+            }
+            applied++;
+            updateMessage(message, stored, tx);
+            if("COMPLAINED".equals(event.type()) || ("BOUNCED".equals(event.type()) && "HARD".equals(event.bounceType())))
+            {
+               EmailTrackingStore.suppress(message, stored, "ALL", "COMPLAINED".equals(event.type()) ? "COMPLAINT" : "HARD_BOUNCE", tx);
+               complaint |= "COMPLAINED".equals(event.type());
+            }
+            else if("UNSUBSCRIBED".equals(event.type()))
+            {
+               EmailTrackingStore.suppress(message, stored, message.getValueString("category"), "UNSUBSCRIBE", tx);
+            }
+         }
+
+         int attempts = row.getValueInteger("attempts") + 1;
+         boolean retry = unmatched > 0 && attempts < MAX_ATTEMPTS;
+         List<String> notes = new ArrayList<>();
+         if(unmatched > 0)
+         {
+            notes.add(unmatched + (unmatched == 1 ? " event did not match a message" : " events did not match a message"));
+         }
+         if(skipped > 0)
+         {
+            notes.add(skipped + (skipped == 1 ? " event was skipped (recipient not on the message)" : " events were skipped (recipient not on the message)"));
+         }
+         EmailStore.update(EmailTables.INBOX, new QRecord().withValue("id", row.getValue("id"))
+            .withValue("status", retry ? "PENDING" : (applied == 0 && unmatched == 0 ? "IGNORED" : "PROCESSED")).withValue("attempts", attempts)
+            .withValue("processedDate", retry ? null : EmailRuntime.clock().instant())
+            .withValue("nextAttemptDate", retry ? EmailRuntime.clock().instant().plusSeconds(60L * EmailRuntime.config().retryMinutesAfterAttempt(attempts)) : null)
+            .withValue("lastError", notes.isEmpty() ? null : String.join("; ", notes)), tx);
+         tx.commit();
+      }
+      catch(Exception e)
+      {
+         fail(observed);
+         return (false);
+      }
+      if(complaint)
+      {
+         complaintAlert();
+      }
+      return (true);
+   }
+
+   /*******************************************************************************
+    ** Canonical mailbox, or null when the provider supplied none that is valid.
+    *******************************************************************************/
+   private static String normalize(String value)
+   {
+      if(value == null || value.isBlank())
+      {
+         return (null);
+      }
+      try
+      {
+         return (EmailTrackingStore.address(value));
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (null);
+      }
+   }
+
+   /*******************************************************************************
+    ** The canonical to, cc and bcc mailboxes of a message; only these may be
+    ** suppressed by an event matched to it.
+    *******************************************************************************/
+   private static Set<String> recipients(QRecord message)
+   {
+      Set<String> set = new HashSet<>();
+      for(String field : List.of("toAddresses", "ccAddresses", "bccAddresses"))
+      {
+         String value = message.getValueString(field);
+         if(value == null || value.isBlank())
+         {
+            continue;
+         }
+         try
+         {
+            for(InternetAddress address : InternetAddress.parse(value, false))
+            {
+               set.add(address.getAddress().toLowerCase(Locale.ROOT));
+            }
+         }
+         catch(jakarta.mail.internet.AddressException e)
+         {
+            // A malformed stored envelope contributes no recipients.
+         }
+      }
+      return (set);
+   }
+
+   /*******************************************************************************
+    ** Match our id first, then the provider id; neither may cross providers.
+    *******************************************************************************/
+   private static QRecord match(EmailEventParser.Event event, Integer providerId, QBackendTransaction tx) throws QException
+   {
+      if(event.messageId() != null && event.messageId().matches("[0-9]{1,10}") && Long.parseLong(event.messageId()) <= Integer.MAX_VALUE)
+      {
+         QRecord message = EmailStore.get(EmailTables.MESSAGE, Integer.valueOf(event.messageId()), tx);
+         if(message != null && providerId.equals(message.getValueInteger("providerId")))
+         {
+            return (message);
+         }
+      }
+      if(event.providerMessageId() == null || event.providerMessageId().isBlank())
+      {
+         return (null);
+      }
+      List<QRecord> rows = SystemWrites.query(EmailTables.MESSAGE, EmailStore.equal("providerId", providerId)
+         .withCriteria("providerMessageId", QCriteriaOperator.EQUALS, event.providerMessageId()), tx);
+      return (rows.size() == 1 ? rows.getFirst() : null);
+   }
+
+   /*******************************************************************************
+    ** Complaint outranks hard bounce, which outranks delivery; never regress.
+    *******************************************************************************/
+   private static void updateMessage(QRecord message, QRecord event, QBackendTransaction tx) throws QException
+   {
+      String type = event.getValueString("eventType");
+      String status = message.getValueString("status");
+      String field = switch(type)
+      {
+         case "DELIVERED" -> "SENT".equals(status) ? "deliveredDate" : null;
+         case "BOUNCED" -> "HARD".equals(event.getValueString("bounceType")) && List.of("SENT", "DELIVERED").contains(status) ? "bouncedDate" : null;
+         case "COMPLAINED" -> List.of("SENT", "DELIVERED", "BOUNCED").contains(status) ? "complainedDate" : null;
+         default -> null;
+      };
+      if(field != null)
+      {
+         EmailStore.update(EmailTables.MESSAGE, new QRecord().withValue("id", message.getValue("id")).withValue("status", type)
+            .withValue(field, event.getValue("occurredDate")), tx);
+      }
+   }
+
+   /*******************************************************************************
+    ** After rollback, only the still-due observed attempt may consume retry budget.
+    *******************************************************************************/
+   private static void fail(QRecord observed) throws QException
+   {
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.PROVIDER)))
+      {
+         EmailTrackingStore.lock(observed.getValueInteger("providerId"), tx);
+         QRecord row = EmailStore.get(EmailTables.INBOX, observed.getValueInteger("id"), tx);
+         if(due(row, observed))
+         {
+            int attempts = row.getValueInteger("attempts") + 1;
+            EmailStore.update(EmailTables.INBOX, new QRecord().withValue("id", row.getValue("id")).withValue("attempts", attempts)
+               .withValue("status", attempts >= MAX_ATTEMPTS ? "FAILED" : "PENDING").withValue("lastError", "Email event processing failed; check message matching and payload validity.")
+               .withValue("nextAttemptDate", attempts >= MAX_ATTEMPTS ? null : EmailRuntime.clock().instant().plusSeconds(60L * EmailRuntime.config().retryMinutesAfterAttempt(attempts))), tx);
+            tx.commit();
+         }
+      }
+   }
+
+   /*******************************************************************************
+    ** Standard Reprocess action rechecks FAILED under the same transaction lock.
+    *******************************************************************************/
+   public static boolean reprocess(Integer id) throws QException
+   {
+      QRecord selected = EmailStore.get(EmailTables.INBOX, id, null);
+      if(selected == null)
+      {
+         return (false);
+      }
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.PROVIDER)))
+      {
+         EmailTrackingStore.lock(selected.getValueInteger("providerId"), tx);
+         QRecord row = EmailStore.get(EmailTables.INBOX, id, tx);
+         if(!"FAILED".equals(row.getValueString("status")))
+         {
+            return (false);
+         }
+         EmailStore.update(EmailTables.INBOX, new QRecord().withValue("id", id).withValue("status", "PENDING").withValue("attempts", 0)
+            .withValue("nextAttemptDate", EmailRuntime.clock().instant()).withValue("lastError", null).withValue("processedDate", null), tx);
+         tx.commit();
+         return (true);
+      }
+   }
+
+   /*******************************************************************************
+    ** Optional alerting cannot turn a committed event into a failed inbox row.
+    *******************************************************************************/
+   private static void complaintAlert()
+   {
+      try
+      {
+         Class.forName("com.kingsrook.qqq.backend.core.alerts.QAlerts");
+         if(SystemWrites.count(EmailTables.EVENT, EmailStore.equal("eventType", "COMPLAINED")
+            .withCriteria("occurredDate", QCriteriaOperator.GREATER_THAN_OR_EQUALS, EmailRuntime.clock().instant().minusSeconds(86400))
+            .withCriteria("occurredDate", QCriteriaOperator.LESS_THAN_OR_EQUALS, EmailRuntime.clock().instant())) > 3)
+         {
+            EmailAlerts.raise(EmailAlerts.COMPLAINT, 0);
+         }
+      }
+      catch(Exception | LinkageError e)
+      {
+         // Alert integration is optional; event data is already committed.
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/EmailTrackingStore.java

@@ -0,0 +1,218 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Locale;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.support.SystemWrites;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import jakarta.mail.internet.InternetAddress;
+
+
+/*******************************************************************************
+ ** DB-only receipt, event deduplication and suppression writes.
+ *******************************************************************************/
+public final class EmailTrackingStore
+{
+   /*******************************************************************************
+    ** Distinguish an authenticated retry from reuse of a Mailgun nonce.
+    *******************************************************************************/
+   public enum Receipt
+   {
+      RECEIVED, DUPLICATE, REPLAY
+   }
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailTrackingStore()
+   {
+   }
+
+   /*******************************************************************************
+    ** Serialize address upserts across providers, then acquire the dispatcher lock.
+    ** Every tracking writer uses this order and does no network I/O while locked.
+    *******************************************************************************/
+   public static QRecord lock(Integer providerId, QBackendTransaction tx) throws QException
+   {
+      List<QRecord> providers = SystemWrites.query(EmailTables.PROVIDER, new QQueryFilter().withOrderBy(new QFilterOrderBy("id")).withLimit(1), tx);
+      if(providers.isEmpty())
+      {
+         throw (new QException("Email provider unavailable"));
+      }
+      EmailStore.lockProvider(providers.getFirst().getValueInteger("id"), tx);
+      QRecord provider = EmailStore.lockProvider(providerId, tx);
+      if(provider == null)
+      {
+         throw (new QException("Email provider unavailable"));
+      }
+      return (provider);
+   }
+
+   /*******************************************************************************
+    ** A provider lock avoids expected duplicate SQL errors (and payload logging).
+    ** Unique constraints remain the final database guard.
+    *******************************************************************************/
+   public static Receipt receive(QRecord provider, String externalId, String nonce, byte[] bytes, String note) throws QException
+   {
+      Integer providerId = provider.getValueInteger("id");
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.PROVIDER)))
+      {
+         EmailStore.lockProvider(providerId, tx);
+         QQueryFilter filter = EmailStore.equal("providerId", providerId);
+         if(nonce != null && SystemWrites.count(EmailTables.INBOX, filter.clone().withCriteria("nonce", QCriteriaOperator.EQUALS, nonce), tx) > 0)
+         {
+            return (Receipt.REPLAY);
+         }
+         if(SystemWrites.count(EmailTables.INBOX, filter.withCriteria("externalEventId", QCriteriaOperator.EQUALS, externalId), tx) > 0)
+         {
+            return (Receipt.DUPLICATE);
+         }
+         var now = EmailRuntime.clock().instant();
+         QRecord row = new QRecord().withValue("providerId", providerId).withValue("kind", provider.getValue("kind"))
+            .withValue("externalEventId", externalId).withValue("nonce", nonce).withValue("status", note == null ? "PENDING" : "IGNORED")
+            .withValue("attempts", 0).withValue("nextAttemptDate", note == null ? now : null).withValue("lastError", note)
+            .withValue("payloadJson", new String(bytes, StandardCharsets.UTF_8)).withValue("payloadSha256", WebhookVerification.hash(bytes))
+            .withValue("receivedDate", now).withValue("processedDate", note == null ? null : now);
+         copySecurity(provider, row);
+         insert(EmailTables.INBOX, row, tx);
+         tx.commit();
+         return (Receipt.RECEIVED);
+      }
+      catch(QException e)
+      {
+         // Re-query after rollback: a unique violation aborts a PostgreSQL transaction.
+         if(nonce != null && SystemWrites.count(EmailTables.INBOX, EmailStore.equal("providerId", providerId)
+            .withCriteria("nonce", QCriteriaOperator.EQUALS, nonce)) > 0)
+         {
+            return (Receipt.REPLAY);
+         }
+         if(SystemWrites.count(EmailTables.INBOX, EmailStore.equal("providerId", providerId)
+            .withCriteria("externalEventId", QCriteriaOperator.EQUALS, externalId)) > 0)
+         {
+            return (Receipt.DUPLICATE);
+         }
+         throw (new QException("Email inbox write failed"));
+      }
+   }
+
+   /*******************************************************************************
+    ** Fail atomically without exposing input values or database diagnostics.
+    *******************************************************************************/
+   public static QRecord insert(String table, QRecord row, QBackendTransaction tx) throws QException
+   {
+      List<QRecord> records = SystemWrites.insert(table, List.of(row), tx).getRecords();
+      if(records.isEmpty() || records.getFirst().getValueInteger("id") == null || (records.getFirst().getErrors() != null && !records.getFirst().getErrors().isEmpty()))
+      {
+         throw (new QException("Email tracking write failed"));
+      }
+      return (records.getFirst());
+   }
+
+   /*******************************************************************************
+    ** Preserve host tenant security on child and suppression records.
+    *******************************************************************************/
+   public static void copySecurity(QRecord source, QRecord target)
+   {
+      for(var field : EmailRuntime.config().getSecurityFields())
+      {
+         target.withValue(field.getName(), source.getValue(field.getName()));
+      }
+   }
+
+   /*******************************************************************************
+    ** Insert a recipient event once even across overlapping provider batches.
+    *******************************************************************************/
+   public static QRecord event(QRecord message, EmailEventParser.Event event, String key, QBackendTransaction tx) throws QException
+   {
+      if(SystemWrites.count(EmailTables.EVENT, EmailStore.equal("eventKey", key), tx) > 0)
+      {
+         return (null);
+      }
+      QRecord row = new QRecord().withValue("messageId", message.getValue("id")).withValue("providerId", message.getValue("providerId"))
+         .withValue("eventType", event.type()).withValue("bounceType", event.bounceType()).withValue("recipient", address(event.recipient()))
+         .withValue("occurredDate", event.occurred()).withValue("detail", event.detail()).withValue("url", "CLICKED".equals(event.type()) ? event.url() : null)
+         .withValue("eventKey", key);
+      copySecurity(message, row);
+      return (insert(EmailTables.EVENT, row, tx));
+   }
+
+   /*******************************************************************************
+    ** Upsert without weakening a complaint or shortening an existing suppression.
+    ** All callers hold the common tracking lock throughout their transaction.
+    *******************************************************************************/
+   public static void suppress(QRecord message, QRecord event, String scope, String reason, QBackendTransaction tx) throws QException
+   {
+      if("UNSUBSCRIBE".equals(reason) && !List.of("MARKETING", "NOTIFICATION").contains(scope == null ? "" : scope))
+      {
+         return;
+      }
+      String address = event.getValueString("recipient");
+      List<QRecord> existing = SystemWrites.query(EmailTables.SUPPRESSION, EmailStore.equal("address", address)
+         .withCriteria("scope", QCriteriaOperator.EQUALS, scope), tx);
+      QRecord row = new QRecord().withValue("address", address).withValue("scope", scope).withValue("reason", reason)
+         .withValue("sourceMessageId", message.getValue("id")).withValue("sourceEventId", event.getValue("id")).withValue("expiresDate", null);
+      copySecurity(message, row);
+      if(existing.isEmpty())
+      {
+         row.withValue("createdDate", EmailRuntime.clock().instant());
+         insert(EmailTables.SUPPRESSION, row, tx);
+      }
+      else
+      {
+         QRecord old = existing.getFirst();
+         if("COMPLAINT".equals(old.getValueString("reason")))
+         {
+            row.withValue("reason", "COMPLAINT");
+         }
+         row.withValue("id", old.getValue("id"));
+         EmailStore.update(EmailTables.SUPPRESSION, row, tx);
+      }
+   }
+
+   /*******************************************************************************
+    ** Canonical mailbox for event deduplication and suppression lookup.
+    *******************************************************************************/
+   public static String address(String value)
+   {
+      try
+      {
+         InternetAddress address = new InternetAddress(value, true);
+         address.validate();
+         return (address.getAddress().toLowerCase(Locale.ROOT));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalArgumentException("Email event recipient is invalid"));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/EmailUnsubscribe.java

@@ -0,0 +1,132 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qbits.email.metadata.EmailTables;
+import com.kingsrook.qbits.email.render.EmailUnsubscribeLinks;
+import com.kingsrook.qbits.email.support.EmailStore;
+import com.kingsrook.qbits.email.template.EmailTemplateEngine;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Stateless token validation and atomic, idempotent category opt-out.
+ *******************************************************************************/
+public final class EmailUnsubscribe
+{
+   /*******************************************************************************
+    ** Resolve the signed message and its single recipient, without writes.
+    *******************************************************************************/
+   public QRecord resolve(String token) throws QException
+   {
+      return (resolve(token, null));
+   }
+
+   /*******************************************************************************
+    ** Recheck the binding against the same transaction used for suppression.
+    *******************************************************************************/
+   private QRecord resolve(String token, QBackendTransaction transaction) throws QException
+   {
+      JSONObject payload = EmailUnsubscribeLinks.verify(token);
+      if(payload == null)
+      {
+         return (null);
+      }
+      try
+      {
+         QRecord message = EmailStore.get(EmailTables.MESSAGE, Integer.valueOf(payload.getString("messageId")), transaction);
+         if(message == null || !payload.getString("category").equals(message.getValueString("category")))
+         {
+            return (null);
+         }
+         String recipient = EmailUnsubscribeLinks.recipient(message.getValueString("toAddresses"), message.getValueString("ccAddresses"), message.getValueString("bccAddresses"));
+         String hash = payload.getString("addressHash");
+         // Safe legacy links remain valid only after the single-mailbox check above.
+         String legacyEnvelope = message.getValueString("toAddresses") + "," + message.getValueString("ccAddresses") + "," + message.getValueString("bccAddresses");
+         boolean matches = WebhookVerification.equal(hash, WebhookVerification.hash(recipient.getBytes(StandardCharsets.UTF_8)))
+            || WebhookVerification.equal(hash, WebhookVerification.hash(legacyEnvelope.getBytes(StandardCharsets.UTF_8)));
+         return (matches ? message : null);
+      }
+      catch(IllegalArgumentException | org.json.JSONException e)
+      {
+         return (null);
+      }
+   }
+
+   /*******************************************************************************
+    ** Opt out only the signed mailbox; reject changed or multi-recipient envelopes.
+    ** Never display those addresses on the public page or emit them to logs.
+    *******************************************************************************/
+   public void unsubscribe(String token) throws QException
+   {
+      QRecord initial = resolve(token);
+      if(initial == null)
+      {
+         throw (new IllegalArgumentException("Invalid unsubscribe link"));
+      }
+      try(QBackendTransaction tx = QBackendTransaction.openFor(new UpdateInput(EmailTables.PROVIDER)))
+      {
+         EmailTrackingStore.lock(initial.getValueInteger("providerId"), tx);
+         QRecord message = resolve(token, tx);
+         if(message == null || !initial.getValueInteger("providerId").equals(message.getValueInteger("providerId")))
+         {
+            throw (new IllegalArgumentException("Invalid unsubscribe link"));
+         }
+         String recipient = EmailUnsubscribeLinks.recipient(message.getValueString("toAddresses"), message.getValueString("ccAddresses"), message.getValueString("bccAddresses"));
+         String key = "unsubscribe:" + message.getValueInteger("id") + ":" + WebhookVerification.hash(recipient.getBytes(StandardCharsets.UTF_8));
+         var event = new EmailEventParser.Event(key, message.getValueString("id"), null, "UNSUBSCRIBED", null, recipient, EmailRuntime.clock().instant(), null, null);
+         QRecord stored = EmailTrackingStore.event(message, event, key, tx);
+         if(stored == null)
+         {
+            stored = com.kingsrook.qbits.email.support.SystemWrites.query(EmailTables.EVENT, EmailStore.equal("eventKey", key), tx).getFirst();
+         }
+         EmailTrackingStore.suppress(message, stored, message.getValueString("category"), "UNSUBSCRIBE", tx);
+         tx.commit();
+      }
+   }
+
+   /*******************************************************************************
+    ** Self-contained accessible page; an empty form action posts to this same URL.
+    *******************************************************************************/
+   public String page(QRecord message, boolean confirmed) throws QException
+   {
+      QRecord brand = message.getValueInteger("brandId") == null ? null : EmailStore.get(EmailTables.BRAND, message.getValueInteger("brandId"), null);
+      String label = brand == null || brand.getValueString("label") == null ? EmailRuntime.config().getAppLabel() : brand.getValueString("label");
+      String category = "MARKETING".equals(message.getValueString("category")) ? "Marketing" : "Notification";
+      String question = confirmed ? "You are unsubscribed from " + category + " email from " + label + "."
+         : "Unsubscribe from " + category + " email from " + label + "?";
+      return ("<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">"
+         + "<meta name=\"color-scheme\" content=\"light dark\"><title>Email preferences</title><style>"
+         + ":root{color-scheme:light dark}*{box-sizing:border-box}body{margin:0;padding:20px;font:18px/1.5 system-ui;background:#fff;color:#172033}"
+         + "main{max-width:560px;margin:40px auto;overflow-wrap:anywhere}h1{font-size:1.5rem}button{max-width:100%;padding:12px 20px;font:inherit;background:#174ea6;color:#fff;border:0;border-radius:6px;cursor:pointer}"
+         + "@media(prefers-color-scheme:dark){body{background:#111827;color:#f9fafb}button{background:#a9c7ff;color:#111827}}</style></head><body><main><p>"
+         + EmailTemplateEngine.escape(label) + "</p><h1>" + EmailTemplateEngine.escape(question) + "</h1>"
+         + (confirmed ? "" : "<form method=\"post\"><input type=\"hidden\" name=\"confirm\" value=\"unsubscribe\"><button type=\"submit\">Unsubscribe</button></form>")
+         + "</main></body></html>");
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/MailgunVerifier.java

@@ -0,0 +1,65 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.HexFormat;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** Authenticate Mailgun; the durable inbox separately arbitrates nonce replay.
+ *******************************************************************************/
+public final class MailgunVerifier
+{
+   /*******************************************************************************
+    ** Verify timestamp, token and hexadecimal HMAC without retaining the key.
+    *******************************************************************************/
+   public boolean verify(JSONObject payload, String secret, Instant now)
+   {
+      if(secret == null || secret.isBlank())
+      {
+         return (false);
+      }
+      try
+      {
+         JSONObject signed = payload.getJSONObject("signature");
+         String timestamp = signed.get("timestamp").toString();
+         String token = signed.getString("token");
+         if(token.isBlank() || token.length() > 500 || !WebhookVerification.fresh(timestamp, now))
+         {
+            return (false);
+         }
+         Mac mac = Mac.getInstance("HmacSHA256");
+         mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
+         String expected = HexFormat.of().formatHex(mac.doFinal((timestamp + token).getBytes(StandardCharsets.UTF_8)));
+         return (WebhookVerification.equal(expected, signed.getString("signature")));
+      }
+      catch(Exception e)
+      {
+         return (false);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/PostmarkVerifier.java

@@ -0,0 +1,52 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+
+/*******************************************************************************
+ ** Postmark authenticates with fixed username postmark and a resolved password.
+ *******************************************************************************/
+public final class PostmarkVerifier
+{
+   /*******************************************************************************
+    ** Verify HTTP Basic credentials without logging or returning either value.
+    *******************************************************************************/
+   public boolean verify(String authorization, String secret)
+   {
+      if(secret == null || secret.isBlank() || authorization == null || !authorization.regionMatches(true, 0, "Basic ", 0, 6))
+      {
+         return (false);
+      }
+      try
+      {
+         String credentials = new String(Base64.getDecoder().decode(authorization.substring(6)), StandardCharsets.UTF_8);
+         return (WebhookVerification.equal("postmark:" + secret, credentials));
+      }
+      catch(IllegalArgumentException e)
+      {
+         return (false);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/SendGridVerifier.java

@@ -0,0 +1,60 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.security.KeyFactory;
+import java.security.Signature;
+import java.security.spec.X509EncodedKeySpec;
+import java.time.Instant;
+import java.util.Base64;
+
+
+/*******************************************************************************
+ ** Verify SendGrid's timestamp and raw body with its DER encoded EC public key.
+ *******************************************************************************/
+public final class SendGridVerifier
+{
+   /*******************************************************************************
+    ** The timestamp bytes precede the unchanged request body.
+    *******************************************************************************/
+   public boolean verify(byte[] body, String signature, String timestamp, String secret, Instant now)
+   {
+      if(secret == null || secret.isBlank() || signature == null || !WebhookVerification.fresh(timestamp, now))
+      {
+         return (false);
+      }
+      try
+      {
+         var key = KeyFactory.getInstance("EC").generatePublic(new X509EncodedKeySpec(Base64.getDecoder().decode(secret)));
+         Signature verifier = Signature.getInstance("SHA256withECDSA");
+         verifier.initVerify(key);
+         verifier.update(timestamp.getBytes(StandardCharsets.UTF_8));
+         verifier.update(body);
+         return (verifier.verify(Base64.getDecoder().decode(signature)));
+      }
+      catch(Exception e)
+      {
+         return (false);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/SnsVerifier.java

@@ -0,0 +1,219 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.nio.charset.StandardCharsets;
+import java.security.Signature;
+import java.security.cert.CertificateFactory;
+import java.security.cert.X509Certificate;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Base64;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import com.kingsrook.qbits.email.transport.EmailHttp;
+import org.json.JSONObject;
+
+
+/*******************************************************************************
+ ** SNS verification with HTTPS AWS-only certificate retrieval, memory caching (including
+ ** a five-minute cache of fetch failures) and a freshness window on the signed Timestamp.
+ *******************************************************************************/
+public final class SnsVerifier
+{
+   private final EmailHttp http;
+   private static final Duration MAX_AGE = Duration.ofHours(1);
+   private static final Duration MAX_FUTURE = Duration.ofMinutes(5);
+   private static final Duration FAILURE_TTL = Duration.ofMinutes(5);
+
+   private final Map<String, X509Certificate> certificates = new ConcurrentHashMap<>();
+   private final Map<String, Instant> failures = new ConcurrentHashMap<>();
+
+   /*******************************************************************************
+    ** Default bounded HTTPS transport without redirects.
+    *******************************************************************************/
+   public SnsVerifier()
+   {
+      this(EmailHttp::sendJdk);
+   }
+
+   /*******************************************************************************
+    ** Inject HTTP for deterministic certificate and confirmation tests.
+    *******************************************************************************/
+   public SnsVerifier(EmailHttp http)
+   {
+      this.http = http;
+   }
+
+   /*******************************************************************************
+    ** Strict URL boundary applied before every network operation.
+    *******************************************************************************/
+   public static boolean allowedUrl(String value, boolean certificate)
+   {
+      try
+      {
+         URI uri = URI.create(value);
+         return ("https".equals(uri.getScheme()) && uri.getHost() != null
+            && uri.getHost().matches("^sns\\.[a-z0-9-]+\\.amazonaws\\.com(\\.cn)?$")
+            && uri.getUserInfo() == null && (uri.getPort() == -1 || uri.getPort() == 443) && uri.getFragment() == null
+            && (!certificate || (uri.getPath().endsWith(".pem") && uri.getQuery() == null)));
+      }
+      catch(RuntimeException e)
+      {
+         return (false);
+      }
+   }
+
+   /*******************************************************************************
+    ** AWS's fixed order includes the final newline and optional Subject only.
+    *******************************************************************************/
+   public static String canonical(JSONObject payload)
+   {
+      String type = payload.getString("Type");
+      List<String> fields;
+      if("Notification".equals(type))
+      {
+         fields = payload.has("Subject") ? List.of("Message", "MessageId", "Subject", "Timestamp", "TopicArn", "Type")
+            : List.of("Message", "MessageId", "Timestamp", "TopicArn", "Type");
+      }
+      else if("SubscriptionConfirmation".equals(type) || "UnsubscribeConfirmation".equals(type))
+      {
+         fields = List.of("Message", "MessageId", "SubscribeURL", "Timestamp", "Token", "TopicArn", "Type");
+      }
+      else
+      {
+         throw (new IllegalArgumentException("Unsupported SNS envelope"));
+      }
+      StringBuilder value = new StringBuilder();
+      for(String field : fields)
+      {
+         value.append(field).append('\n').append(payload.getString(field)).append('\n');
+      }
+      return (value.toString());
+   }
+
+   /*******************************************************************************
+    ** Authenticate the topic and signature; no confirmation before success.
+    *******************************************************************************/
+   public boolean verify(JSONObject payload, String topic, Instant now) throws IOException, InterruptedException
+   {
+      try
+      {
+         String url = payload.getString("SigningCertURL");
+         if(topic == null || topic.isBlank() || !topic.equals(payload.getString("TopicArn")) || !allowedUrl(url, true))
+         {
+            return (false);
+         }
+         String algorithm = switch(payload.getString("SignatureVersion"))
+         {
+            case "1" -> "SHA1withRSA";
+            case "2" -> "SHA256withRSA";
+            default -> null;
+         };
+         if(algorithm == null)
+         {
+            return (false);
+         }
+         Instant stamp = Instant.parse(payload.getString("Timestamp"));
+         if(stamp.isBefore(now.minus(MAX_AGE)) || stamp.isAfter(now.plus(MAX_FUTURE)))
+         {
+            return (false);
+         }
+         String canonical = canonical(payload);
+         X509Certificate certificate = certificates.get(url);
+         if(certificate == null || certificate.getNotAfter().toInstant().isBefore(now))
+         {
+            Instant failed = failures.get(url);
+            if(failed != null && failed.plus(FAILURE_TTL).isAfter(now))
+            {
+               throw (new IOException("SNS verification service unavailable"));
+            }
+            byte[] pem;
+            try
+            {
+               pem = get(url).getBytes(StandardCharsets.UTF_8);
+            }
+            catch(IOException e)
+            {
+               if(failures.size() >= 64)
+               {
+                  failures.clear();
+               }
+               failures.put(url, now);
+               throw (e);
+            }
+            certificate = (X509Certificate) CertificateFactory.getInstance("X.509").generateCertificate(new ByteArrayInputStream(pem));
+            certificate.checkValidity(Date.from(now));
+            if(certificates.size() >= 64)
+            {
+               certificates.clear();
+            }
+            certificates.put(url, certificate);
+         }
+         certificate.checkValidity(Date.from(now));
+         Signature verifier = Signature.getInstance(algorithm);
+         verifier.initVerify(certificate.getPublicKey());
+         verifier.update(canonical.getBytes(StandardCharsets.UTF_8));
+         return (verifier.verify(Base64.getDecoder().decode(payload.getString("Signature"))));
+      }
+      catch(IOException | InterruptedException e)
+      {
+         throw (e);
+      }
+      catch(Exception e)
+      {
+         return (false);
+      }
+   }
+
+   /*******************************************************************************
+    ** Caller invokes this only after verifying the signed confirmation envelope.
+    *******************************************************************************/
+   public void confirm(JSONObject payload) throws IOException, InterruptedException
+   {
+      String url = payload.getString("SubscribeURL");
+      if(!allowedUrl(url, false))
+      {
+         throw (new IllegalArgumentException("Invalid SNS confirmation URL"));
+      }
+      get(url);
+   }
+
+   /*******************************************************************************
+    ** Fixed request timeout, no redirects, and no provider response diagnostics.
+    *******************************************************************************/
+   private String get(String url) throws IOException, InterruptedException
+   {
+      var response = http.send(HttpRequest.newBuilder(URI.create(url)).timeout(Duration.ofSeconds(30)).GET().build());
+      if(response.statusCode() != 200 || response.body() == null || response.body().length() > 65536)
+      {
+         throw (new IOException("SNS verification service unavailable"));
+      }
+      return (response.body());
+   }
+}

src/main/java/com/kingsrook/qbits/email/tracking/WebhookVerification.java

@@ -0,0 +1,105 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.tracking;
+
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.Instant;
+import java.util.HexFormat;
+import com.kingsrook.qbits.email.EmailQBitConfig;
+import com.kingsrook.qbits.email.EmailRuntime;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Small shared verification primitives. Errors never retain request data.
+ *******************************************************************************/
+public final class WebhookVerification
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private WebhookVerification()
+   {
+   }
+
+   /*******************************************************************************
+    ** Resolve only an allowlisted webhook secret; null means unavailable.
+    *******************************************************************************/
+   public static String secret(QRecord provider)
+   {
+      EmailQBitConfig config = EmailRuntime.config();
+      String name = provider.getValueString("webhookSecretEnvName");
+      try
+      {
+         if(name != null && EmailQBitConfig.ENV_NAME.matcher(name).matches() && config.effectiveAllowedEnvNames(provider.getValueString("kind")).contains(name))
+         {
+            String value = config.getSecretResolver().apply(name);
+            return (value == null || value.isBlank() ? null : value);
+         }
+      }
+      catch(RuntimeException e)
+      {
+         return (null);
+      }
+      return (null);
+   }
+
+   /*******************************************************************************
+    ** Compare bytes without data-dependent early exits.
+    *******************************************************************************/
+   public static boolean equal(String expected, String actual)
+   {
+      return (expected != null && actual != null && MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), actual.getBytes(StandardCharsets.UTF_8)));
+   }
+
+   /*******************************************************************************
+    ** Reject timestamps outside five minutes, including future timestamps.
+    *******************************************************************************/
+   public static boolean fresh(String timestamp, Instant now)
+   {
+      try
+      {
+         Instant time = Instant.ofEpochSecond(Long.parseLong(timestamp));
+         return (!time.isBefore(now.minusSeconds(300)) && !time.isAfter(now.plusSeconds(300)));
+      }
+      catch(RuntimeException e)
+      {
+         return (false);
+      }
+   }
+
+   /*******************************************************************************
+    ** Stable payload and event fingerprints, never payload diagnostics.
+    *******************************************************************************/
+   public static String hash(byte[] bytes)
+   {
+      try
+      {
+         return (HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes)));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalStateException("SHA-256 unavailable"));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/email/transport/EmailEnvelope.java

@@ -31,6 +31,7 @@ import java.util.Map;
 public class EmailEnvelope
 {
    private String messageId;
+   private String rfcMessageId;
    private String from;
    private List<String> to = List.of();
    private List<String> cc = List.of();
@@ -62,6 +63,27 @@ public class EmailEnvelope
    }
 
 
+
+   /*******************************************************************************
+    ** Getter for the persisted RFC 5322 Message-ID, distinct from the outbox row id.
+    *******************************************************************************/
+   public String getRfcMessageId()
+   {
+      return (rfcMessageId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for the persisted RFC 5322 Message-ID.
+    *******************************************************************************/
+   public EmailEnvelope withRfcMessageId(String rfcMessageId)
+   {
+      this.rfcMessageId = rfcMessageId;
+      return (this);
+   }
+
+
    /*******************************************************************************
     ** Getter for from.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/email/transport/EmailHttp.java

@@ -0,0 +1,70 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.transport;
+
+
+import java.io.IOException;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+
+
+/*******************************************************************************
+ ** Shared HTTP seam; no provider SDK, credential cache or filesystem.
+ *******************************************************************************/
+@FunctionalInterface
+public interface EmailHttp
+{
+   /*******************************************************************************
+    ** Exchange one request without retries.
+    *******************************************************************************/
+   HttpResponse<String> send(HttpRequest request) throws IOException, InterruptedException;
+
+
+
+   /*******************************************************************************
+    ** Production requests use HTTPS and never forward credentials on redirects.
+    *******************************************************************************/
+   static HttpResponse<String> sendJdk(HttpRequest request) throws IOException, InterruptedException
+   {
+      if(!"https".equalsIgnoreCase(request.uri().getScheme()))
+      {
+         throw (new IOException("Email HTTP requires HTTPS"));
+      }
+      try(HttpClient client = newClient())
+      {
+         return (client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A bounded, stateless JDK client; the caller closes it after each exchange.
+    *******************************************************************************/
+   static HttpClient newClient()
+   {
+      return (HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).followRedirects(HttpClient.Redirect.NEVER).build());
+   }
+}
+

src/main/java/com/kingsrook/qbits/email/transport/EmailHttpSupport.java

@@ -0,0 +1,234 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.transport;
+
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Properties;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.mail.MessagingException;
+import jakarta.mail.Session;
+
+
+/*******************************************************************************
+ ** Shared serialization, timeouts and sanitized HTTP failures.
+ *******************************************************************************/
+final class EmailHttpSupport
+{
+   static final ObjectMapper JSON = new ObjectMapper();
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EmailHttpSupport()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Use the shared envelope validation even for JSON APIs.
+    *******************************************************************************/
+   static void validate(EmailEnvelope envelope) throws EmailTransportException
+   {
+      try
+      {
+         EmailMime.build(Session.getInstance(new Properties()), envelope);
+      }
+      catch(MessagingException | RuntimeException e)
+      {
+         throw (new EmailTransportException("Invalid email message", true));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Preserve application headers and the stable correlation identifier.
+    *******************************************************************************/
+   static Map<String, String> headers(EmailEnvelope envelope)
+   {
+      Map<String, String> headers = new LinkedHashMap<>();
+      envelope.getHeaders().forEach((name, value) ->
+      {
+         if(!name.equalsIgnoreCase("Bcc") && !name.equalsIgnoreCase("Auto-Submitted") && !name.equalsIgnoreCase("X-QQQ-Email-Id") && !name.equalsIgnoreCase("Message-ID"))
+         {
+            headers.put(name, value);
+         }
+      });
+      headers.put("Auto-Submitted", "auto-generated");
+      headers.put("X-QQQ-Email-Id", envelope.getMessageId());
+      if(envelope.getRfcMessageId() != null)
+      {
+         headers.put("Message-ID", envelope.getRfcMessageId());
+      }
+      return (headers);
+   }
+
+
+
+   /*******************************************************************************
+    ** Serialize only in memory using Jackson already supplied by core.
+    *******************************************************************************/
+   static byte[] json(Object value) throws EmailTransportException
+   {
+      try
+      {
+         return (JSON.writeValueAsBytes(value));
+      }
+      catch(IOException | RuntimeException e)
+      {
+         throw (new EmailTransportException("Invalid email message", true));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve auth before calling; never attach raw exceptions to a safe failure.
+    *******************************************************************************/
+   static HttpResponse<String> post(EmailHttp http, String url, String contentType, String authHeader, String auth, byte[] body) throws EmailTransportException
+   {
+      try
+      {
+         HttpRequest request = HttpRequest.newBuilder(URI.create(url)).timeout(Duration.ofSeconds(30))
+            .header("Content-Type", contentType).header("Accept", "application/json").header(authHeader, auth)
+            .POST(HttpRequest.BodyPublishers.ofByteArray(body)).build();
+         return (http.send(request));
+      }
+      catch(InterruptedException e)
+      {
+         Thread.currentThread().interrupt();
+         throw (new EmailTransportException("Email HTTP request interrupted", false));
+      }
+      catch(IOException e)
+      {
+         throw (new EmailTransportException("Email HTTP temporarily unavailable", false));
+      }
+      catch(RuntimeException e)
+      {
+         throw (new EmailTransportException("Email HTTP configuration invalid", false).withProviderLevel(true));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Unparseable replies must not expose bodies or cause permanent message loss.
+    *******************************************************************************/
+   static JsonNode responseJson(HttpResponse<String> response) throws EmailTransportException
+   {
+      try
+      {
+         JsonNode json = JSON.readTree(response.body());
+         if(json != null && json.isObject())
+         {
+            return (json);
+         }
+      }
+      catch(IOException | RuntimeException e)
+      {
+         // Bodies and parser diagnostics may contain recipient addresses.
+      }
+      throw (new EmailTransportException("Email provider returned an invalid response", false));
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse either Retry-After syntax; the dispatcher applies the one-hour cap.
+    *******************************************************************************/
+   static Duration retryAfter(HttpResponse<String> response)
+   {
+      String value = response.headers().firstValue("Retry-After").orElse("").trim();
+      try
+      {
+         long seconds = Long.parseLong(value);
+         return (seconds < 0 ? null : Duration.ofSeconds(seconds));
+      }
+      catch(RuntimeException e)
+      {
+         try
+         {
+            Duration delay = Duration.between(Instant.now(), ZonedDateTime.parse(value, DateTimeFormatter.RFC_1123_DATE_TIME).toInstant());
+            return (delay.isNegative() ? Duration.ZERO : delay);
+         }
+         catch(RuntimeException ignored)
+         {
+            return (null);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Only numeric status/code and fixed text escape the transport.
+    *******************************************************************************/
+   static EmailTransportException failure(HttpResponse<String> response, String provider, Integer code, boolean permanent, boolean providerLevel)
+   {
+      return (new EmailTransportException(provider + " request failed (HTTP " + response.statusCode()
+         + (code == null ? "" : ", code " + code) + ")", permanent).withProviderLevel(providerLevel).withRetryAfter(retryAfter(response)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Common HTTP precedence: throttling and server errors always remain retryable.
+    *******************************************************************************/
+   static void checkStatus(HttpResponse<String> response, String provider, int success) throws EmailTransportException
+   {
+      int status = response.statusCode();
+      if(status != success)
+      {
+         boolean transientFailure = status == 408 || status == 429 || status >= 500;
+         boolean providerLevel = status == 401 || status == 403 || (status >= 300 && status < 400);
+         throw (failure(response, provider, null, !transientFailure && !providerLevel && status >= 400, providerLevel));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A success must contain a usable id; never mistake a malformed body for success.
+    *******************************************************************************/
+   static EmailTransportResult result(String id) throws EmailTransportException
+   {
+      if(id == null || id.isBlank() || id.length() > 500 || id.contains("\r") || id.contains("\n"))
+      {
+         throw (new EmailTransportException("Email provider returned an invalid message id", false));
+      }
+      return (new EmailTransportResult(id));
+   }
+}
+

src/main/java/com/kingsrook/qbits/email/transport/EmailMime.java

@@ -53,7 +53,26 @@ final class EmailMime
       noLineBreaks(envelope.getFrom());
       noLineBreaks(envelope.getReplyTo());
       noLineBreaks(envelope.getMessageId());
-      MimeMessage message = new MimeMessage(session);
+      noLineBreaks(envelope.getRfcMessageId());
+      String rfcMessageId = envelope.getRfcMessageId();
+      MimeMessage message = new MimeMessage(session)
+      {
+         /*******************************************************************************
+          ** JavaMail may save again when sending; keep the persisted identity each time.
+          *******************************************************************************/
+         @Override
+         protected void updateMessageID() throws MessagingException
+         {
+            if(rfcMessageId == null)
+            {
+               super.updateMessageID();
+            }
+            else
+            {
+               setHeader("Message-ID", rfcMessageId);
+            }
+         }
+      };
       message.setFrom(new InternetAddress(envelope.getFrom(), true));
       recipients(message, Message.RecipientType.TO, envelope.getTo());
       recipients(message, Message.RecipientType.CC, envelope.getCc());

src/main/java/com/kingsrook/qbits/email/transport/EmailProviderSettings.java

@@ -86,6 +86,36 @@ public final class EmailProviderSettings
          || "127.0.0.1".equals(host()) || "::1".equals(host()));
    }
 
+   /*******************************************************************************
+    ** A domain is a single DNS name, never a URL or a path component escape.
+    *******************************************************************************/
+   public static boolean validSendingDomain(String domain)
+   {
+      return (domain != null && domain.length() <= 253
+         && domain.matches("(?i)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+"));
+   }
+
+   /*******************************************************************************
+    ** Tracking is opt-in; null database values mean disabled.
+    *******************************************************************************/
+   boolean enabled(String field)
+   {
+      return (Boolean.TRUE.equals(row.getValueBoolean(field)));
+   }
+
+   /*******************************************************************************
+    ** HTTP providers must never send a missing token as the literal string null.
+    *******************************************************************************/
+   String requiredSecret() throws EmailTransportException
+   {
+      String secret = resolve("secretEnvName");
+      if(secret == null)
+      {
+         throw (new EmailTransportException("Provider needs a secret environment name", false).withProviderLevel(true));
+      }
+      return (secret);
+   }
+
    /*******************************************************************************
     ** Resolve an explicitly named secret immediately before sending.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/email/transport/EmailTransportRegistry.java

@@ -33,13 +33,16 @@ public class EmailTransportRegistry
    private final Map<String, EmailTransport> transports = new HashMap<>();
 
    /*******************************************************************************
-    ** Install the phase (a) transports.
+    ** Install the outbound transports.
     *******************************************************************************/
    public EmailTransportRegistry()
    {
       transports.put("SMTP", new SmtpEmailTransport());
       transports.put("GMAIL_SMTP", new SmtpEmailTransport());
       transports.put("SES", new SesEmailTransport());
+      transports.put("POSTMARK", new PostmarkEmailTransport());
+      transports.put("SENDGRID", new SendGridEmailTransport());
+      transports.put("MAILGUN", new MailgunEmailTransport());
    }
 
    /*******************************************************************************
@@ -59,7 +62,8 @@ public class EmailTransportRegistry
       EmailTransport transport = transports.get(kind);
       if(transport == null)
       {
-         throw (new EmailTransportException("Provider transport not available until phase (b)", true));
+         throw (new EmailTransportException("GMAIL_API".equals(kind)
+            ? "Gmail API sending is specified but not built; use GMAIL_SMTP" : "Unknown email provider kind", true));
       }
       return (transport);
    }

src/main/java/com/kingsrook/qbits/email/transport/MailgunEmailTransport.java

@@ -0,0 +1,136 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.transport;
+
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Base64;
+import java.util.List;
+import java.util.Properties;
+import java.util.UUID;
+import jakarta.mail.MessagingException;
+import jakarta.mail.Session;
+import jakarta.mail.internet.InternetAddress;
+
+
+/*******************************************************************************
+ ** Mailgun MIME upload, entirely in memory, with explicit blind destinations.
+ *******************************************************************************/
+public class MailgunEmailTransport implements EmailTransport
+{
+   private final EmailHttp http;
+
+
+
+   /*******************************************************************************
+    ** Fixed regional production endpoints and JDK HTTP implementation.
+    *******************************************************************************/
+   public MailgunEmailTransport()
+   {
+      this(EmailHttp::sendJdk);
+   }
+
+
+
+   /*******************************************************************************
+    ** Package-visible request/response test seam.
+    *******************************************************************************/
+   MailgunEmailTransport(EmailHttp http)
+   {
+      this.http = http;
+   }
+
+
+
+   /*******************************************************************************
+    ** Envelope destinations include Bcc; serialized MIME never includes its header.
+    *******************************************************************************/
+   @Override
+   public EmailTransportResult send(EmailEnvelope envelope, EmailProviderSettings settings) throws EmailTransportException
+   {
+      String domain = settings.value("sendingDomain");
+      String region = settings.value("region");
+      if(!EmailProviderSettings.validSendingDomain(domain) || (!"US".equals(region) && !"EU".equals(region)))
+      {
+         throw (new EmailTransportException("Mailgun needs a sending domain and US or EU region", false).withProviderLevel(true));
+      }
+      String boundary = "qqq-email-" + UUID.randomUUID();
+      ByteArrayOutputStream body = new ByteArrayOutputStream();
+      try
+      {
+         List<String> destinations = new ArrayList<>();
+         for(List<String> role : List.of(envelope.getTo(), envelope.getCc(), envelope.getBcc()))
+         {
+            for(String value : role)
+            {
+               for(InternetAddress address : InternetAddress.parse(value, true))
+               {
+                  address.validate();
+                  destinations.add(address.getAddress());
+               }
+            }
+         }
+         field(body, boundary, "to", String.join(",", destinations));
+         field(body, boundary, "o:tracking-opens", settings.enabled("trackOpens") ? "yes" : "no");
+         field(body, boundary, "o:tracking-clicks", settings.enabled("trackClicks") ? "yes" : "no");
+         field(body, boundary, "v:qqq_email_id", envelope.getMessageId());
+         if(envelope.getRfcMessageId() != null)
+         {
+            field(body, boundary, "h:Message-Id", envelope.getRfcMessageId());
+         }
+         body.writeBytes(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"message\"; filename=\"message.eml\"\r\n"
+            + "Content-Type: message/rfc822\r\n\r\n").getBytes(StandardCharsets.UTF_8));
+         EmailMime.build(Session.getInstance(new Properties()), envelope).writeTo(body, new String[] {"Bcc"});
+         body.writeBytes(("\r\n--" + boundary + "--\r\n").getBytes(StandardCharsets.UTF_8));
+      }
+      catch(MessagingException | IOException | RuntimeException e)
+      {
+         throw (new EmailTransportException("Invalid email message", true));
+      }
+      String auth = Base64.getEncoder().encodeToString(("api:" + settings.requiredSecret()).getBytes(StandardCharsets.UTF_8));
+      String host = "EU".equals(region) ? "https://api.eu.mailgun.net" : "https://api.mailgun.net";
+      HttpResponse<String> response = EmailHttpSupport.post(http, host + "/v3/" + domain + "/messages.mime",
+         "multipart/form-data; boundary=" + boundary, "Authorization", "Basic " + auth, body.toByteArray());
+      EmailHttpSupport.checkStatus(response, "Mailgun", 200);
+      String id = EmailHttpSupport.responseJson(response).path("id").textValue();
+      if(id != null && id.startsWith("<") && id.endsWith(">"))
+      {
+         id = id.substring(1, id.length() - 1);
+      }
+      return (EmailHttpSupport.result(id));
+   }
+
+
+
+   /*******************************************************************************
+    ** Encode fixed-name UTF-8 multipart fields without touching the filesystem.
+    *******************************************************************************/
+   private static void field(ByteArrayOutputStream body, String boundary, String name, String value)
+   {
+      body.writeBytes(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"" + name + "\"\r\n\r\n"
+         + value + "\r\n").getBytes(StandardCharsets.UTF_8));
+   }
+}
+

src/main/java/com/kingsrook/qbits/email/transport/PostmarkEmailTransport.java

@@ -0,0 +1,129 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.transport;
+
+
+import java.net.http.HttpResponse;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import com.fasterxml.jackson.databind.JsonNode;
+
+
+/*******************************************************************************
+ ** Postmark's single-message API with per-attempt server token resolution.
+ *******************************************************************************/
+public class PostmarkEmailTransport implements EmailTransport
+{
+   private final EmailHttp http;
+
+
+
+   /*******************************************************************************
+    ** Fixed production endpoint and JDK HTTP implementation.
+    *******************************************************************************/
+   public PostmarkEmailTransport()
+   {
+      this(EmailHttp::sendJdk);
+   }
+
+
+
+   /*******************************************************************************
+    ** Package-visible request/response test seam.
+    *******************************************************************************/
+   PostmarkEmailTransport(EmailHttp http)
+   {
+      this.http = http;
+   }
+
+
+
+   /*******************************************************************************
+    ** Send a rendered message; provider response diagnostics never escape.
+    *******************************************************************************/
+   @Override
+   public EmailTransportResult send(EmailEnvelope envelope, EmailProviderSettings settings) throws EmailTransportException
+   {
+      EmailHttpSupport.validate(envelope);
+      Map<String, Object> body = new LinkedHashMap<>();
+      body.put("From", envelope.getFrom());
+      body.put("To", String.join(",", envelope.getTo()));
+      body.put("Cc", String.join(",", envelope.getCc()));
+      body.put("Bcc", String.join(",", envelope.getBcc()));
+      if(envelope.getReplyTo() != null)
+      {
+         body.put("ReplyTo", envelope.getReplyTo());
+      }
+      body.put("Subject", envelope.getSubject());
+      if(envelope.getHtmlBody() != null)
+      {
+         body.put("HtmlBody", envelope.getHtmlBody());
+      }
+      if(envelope.getTextBody() != null)
+      {
+         body.put("TextBody", envelope.getTextBody());
+      }
+      body.put("Headers", EmailHttpSupport.headers(envelope).entrySet().stream()
+         .map(h -> Map.of("Name", h.getKey(), "Value", h.getValue())).toList());
+      String stream = settings.value("messageStream");
+      body.put("MessageStream", stream == null || stream.isBlank() ? "outbound" : stream);
+      body.put("TrackOpens", settings.enabled("trackOpens"));
+      body.put("TrackLinks", settings.enabled("trackClicks") ? "HtmlAndText" : "None");
+      HttpResponse<String> response = EmailHttpSupport.post(http, "https://api.postmarkapp.com/email", "application/json",
+         "X-Postmark-Server-Token", settings.requiredSecret(), EmailHttpSupport.json(body));
+      int status = response.statusCode();
+      if(status == 408 || status == 429 || status >= 500 || status == 401 || status == 403 || (status >= 300 && status < 400))
+      {
+         EmailHttpSupport.checkStatus(response, "Postmark", 200);
+      }
+      JsonNode json;
+      try
+      {
+         json = EmailHttpSupport.responseJson(response);
+      }
+      catch(EmailTransportException e)
+      {
+         EmailHttpSupport.checkStatus(response, "Postmark", 200);
+         throw (e);
+      }
+      Integer code = json.path("ErrorCode").canConvertToInt() ? json.path("ErrorCode").intValue() : null;
+      if(status == 200 && code == null)
+      {
+         throw (new EmailTransportException("Email provider returned an invalid response", false));
+      }
+      if(status != 200 || code == null || code != 0)
+      {
+         // Postmark ErrorCode (not HTTP status) | Classification
+         // 10 bad token                        | provider-level
+         // 300 invalid request, 406 inactive   | permanent message failure
+         // 400/401 sender signature, 405 send disabled, 412 pending approval,
+         // 413 account unapproved, 422 invalid server, 1235/1236 stream,
+         // 1480 IP restriction                 | provider-level
+         // HTTP 429 / 5xx                      | transient, takes precedence
+         // Other request codes                | permanent (unknown 200 is transient)
+         boolean providerLevel = code != null && Set.of(10, 400, 401, 405, 412, 413, 422, 1235, 1236, 1480).contains(code);
+         throw (EmailHttpSupport.failure(response, "Postmark", code, !providerLevel && (status >= 400 || code != null && code != 0), providerLevel));
+      }
+      return (EmailHttpSupport.result(json.path("MessageID").textValue()));
+   }
+}
+

src/main/java/com/kingsrook/qbits/email/transport/SendGridEmailTransport.java

@@ -0,0 +1,145 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.email.transport;
+
+
+import java.net.http.HttpResponse;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import jakarta.mail.internet.AddressException;
+import jakarta.mail.internet.InternetAddress;
+
+
+/*******************************************************************************
+ ** SendGrid v3 mail send with explicit per-message tracking settings.
+ *******************************************************************************/
+public class SendGridEmailTransport implements EmailTransport
+{
+   private static final Set<String> RESERVED_HEADERS = Set.of("x-sg-id", "x-sg-eid", "received", "dkim-signature",
+      "content-type", "content-transfer-encoding", "to", "from", "subject", "reply-to", "cc", "bcc");
+   private final EmailHttp http;
+
+
+
+   /*******************************************************************************
+    ** Fixed production endpoint and JDK HTTP implementation.
+    *******************************************************************************/
+   public SendGridEmailTransport()
+   {
+      this(EmailHttp::sendJdk);
+   }
+
+
+
+   /*******************************************************************************
+    ** Package-visible request/response test seam.
+    *******************************************************************************/
+   SendGridEmailTransport(EmailHttp http)
+   {
+      this.http = http;
+   }
+
+
+
+   /*******************************************************************************
+    ** Build one personalization, keeping blind recipients out of custom headers.
+    *******************************************************************************/
+   @Override
+   public EmailTransportResult send(EmailEnvelope envelope, EmailProviderSettings settings) throws EmailTransportException
+   {
+      EmailHttpSupport.validate(envelope);
+      Map<String, Object> body = new LinkedHashMap<>();
+      Map<String, Object> personalization = new LinkedHashMap<>();
+      personalization.put("to", addresses(envelope.getTo()));
+      if(!envelope.getCc().isEmpty())
+      {
+         personalization.put("cc", addresses(envelope.getCc()));
+      }
+      if(!envelope.getBcc().isEmpty())
+      {
+         personalization.put("bcc", addresses(envelope.getBcc()));
+      }
+      body.put("personalizations", List.of(personalization));
+      body.put("from", addresses(List.of(envelope.getFrom())).getFirst());
+      if(envelope.getReplyTo() != null)
+      {
+         body.put("reply_to", addresses(List.of(envelope.getReplyTo())).getFirst());
+      }
+      body.put("subject", envelope.getSubject());
+      List<Map<String, String>> content = new ArrayList<>();
+      if(envelope.getTextBody() != null && !envelope.getTextBody().isEmpty())
+      {
+         content.add(Map.of("type", "text/plain", "value", envelope.getTextBody()));
+      }
+      if(envelope.getHtmlBody() != null && !envelope.getHtmlBody().isEmpty())
+      {
+         content.add(Map.of("type", "text/html", "value", envelope.getHtmlBody()));
+      }
+      body.put("content", content);
+      Map<String, String> headers = EmailHttpSupport.headers(envelope);
+      headers.keySet().removeIf(name -> RESERVED_HEADERS.contains(name.toLowerCase(Locale.ROOT)));
+      body.put("headers", headers);
+      body.put("custom_args", Map.of("qqq_email_id", envelope.getMessageId()));
+      body.put("tracking_settings", Map.of("open_tracking", Map.of("enable", settings.enabled("trackOpens")),
+         "click_tracking", Map.of("enable", settings.enabled("trackClicks"), "enable_text", settings.enabled("trackClicks"))));
+      HttpResponse<String> response = EmailHttpSupport.post(http, "https://api.sendgrid.com/v3/mail/send", "application/json",
+         "Authorization", "Bearer " + settings.requiredSecret(), EmailHttpSupport.json(body));
+      EmailHttpSupport.checkStatus(response, "SendGrid", 202);
+      return (EmailHttpSupport.result(response.headers().firstValue("X-Message-Id").orElse(null)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Convert mailboxes without losing their decoded display names.
+    *******************************************************************************/
+   private static List<Map<String, String>> addresses(List<String> values) throws EmailTransportException
+   {
+      List<Map<String, String>> result = new ArrayList<>();
+      try
+      {
+         for(String value : values)
+         {
+            for(InternetAddress address : InternetAddress.parse(value, true))
+            {
+               address.validate();
+               Map<String, String> entry = new LinkedHashMap<>();
+               entry.put("email", address.getAddress());
+               if(address.getPersonal() != null)
+               {
+                  entry.put("name", address.getPersonal());
+               }
+               result.add(entry);
+            }
+         }
+      }
+      catch(AddressException e)
+      {
+         throw (new EmailTransportException("Invalid email message", true));
+      }
+      return (result);
+   }
+}
+

src/main/java/com/kingsrook/qbits/email/transport/SesEmailTransport.java

@@ -50,6 +50,9 @@ import software.amazon.awssdk.services.sesv2.model.SesV2Exception;
 
 /*******************************************************************************
  ** SES v2 raw MIME transport; credentials are resolved only for an attempt.
+ ** The raw request carries the stored Message-ID, but SES replaces it downstream.
+ ** Receiver deduplication by that header is unavailable with SES; X-QQQ-Email-Id
+ ** remains the application correlation header. See docs/DURABLE-JOBS.md.
  *******************************************************************************/
 public class SesEmailTransport implements EmailTransport
 {
@@ -64,9 +67,9 @@ public class SesEmailTransport implements EmailTransport
    }
 
    /*******************************************************************************
-    ** Package-visible fake-client seam.
+    ** Injectable client factory for embedded hosts and local demonstrations.
     *******************************************************************************/
-   SesEmailTransport(Function<SesV2ClientBuilder, SesV2Client> clientFactory)
+   public SesEmailTransport(Function<SesV2ClientBuilder, SesV2Client> clientFactory)
    {
       this.clientFactory = clientFactory;
    }

src/main/java/com/kingsrook/qbits/email/transport/SmtpEmailTransport.java

@@ -48,6 +48,12 @@ public class SmtpEmailTransport implements EmailTransport
       {
          throw (new EmailTransportException("SMTP sign-in needs STARTTLS or TLS", false).withProviderLevel(true));
       }
+      if("GMAIL_SMTP".equals(settings.value("kind"))
+         && (settings.value("usernameEnvName") == null || settings.value("secretEnvName") == null
+         || (settings.value("security") != null && !"STARTTLS".equals(settings.value("security")))))
+      {
+         throw (new EmailTransportException("Gmail SMTP needs both credential names and STARTTLS", false).withProviderLevel(true));
+      }
       Properties properties = new Properties();
       properties.setProperty("mail.smtp.connectiontimeout", "10000");
       properties.setProperty("mail.smtp.timeout", "15000");