Keep template rendering and delivery ownership in email, with caller-scoped permissions and checked replay provenance.
Co-Authored-By: Codex <noreply@openai.com>
Signed-off-by: James Maes <james@kof22.com>
The readiness message was only "Email configuration incomplete" plus a code.
It now names each gap in plain words with the Email app path to fix it, and
notes that transactional email is unaffected by marketing-only gaps. The
failedChecks detail is unchanged; howToFix carries the same text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Email health tile showed the HealthStatus name (UP/DEGRADED/DOWN/UNKNOWN). It now shows Healthy / Degraded / Down, and "Not checked yet" when no
check has reported, with the check cadence in the context line. The drill to health_check is unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The producer read a literal version, so released artifacts reported a stale
or -SNAPSHOT version. qbit-email.properties (version=${project.version}) is
Maven-filtered and the producer loads it; tests assert producer == bundle ==
artifact version.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The qbit metadata version is hardcoded (0.1.0), so it cannot be compared with
the filtered bundle version. Check that the bundle resolved a real
x.y.z[-SNAPSHOT|-RC.n] version instead of a literal.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The producer test pinned the bundle version to 0.1.0-SNAPSHOT, so the
0.1.0-RC.7 release build failed (bundle and qbit both 0.1.0-RC.6 locally).
Compare the bundle with the produced qbit's version instead.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On release branches the bundle's version and the producer's differed, so the
bundle test that asserts they match failed, and released bundles recorded
SNAPSHOT as their provenance. help/*.yaml is now filtered:
version: ${project.version}.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Host-neutral help (deployment-specific facts removed), registered with
HelpBundles, gated by HelpBundleAssertions. QQQ 4.1.0-RC.7.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeps develop's liquibase-core test dependency next to the Postgres
Testcontainers dependencies, and both changelog entries. H2 tests load
src/test/resources/email-h2.sql (FKs in H2 syntax), never the Postgres DDL.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds email-defaults.changelog.sql (non-default neutral brand, only when no brand
exists; tested through real Liquibase), help for the app and every table, a
Setup card on the home, guardrail tests and docs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
email_template.ownerQbit was stored but never read. Messages sent from a
template now name its owner qbit as senderQbit unless the request names one,
the built-in secure-message template sets it, and the field is read-only.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Built on QQQ 4.1.0-RC.7, which has the durable jobs side-effects outbox.
- EmailJobEffectTarget implements core's EffectTarget.
- Delivery hands the email to qbit-email's own outbox with the effect's
idempotency key, so it lands exactly once per key, with the fixed
Message-ID. The result is SENT with the message id, or FAILED when
refused.
- It runs as the job owner (JobSessions.forJob). If the owner can no longer
send, the result is FAILED, never UNKNOWN.
- Reconcile looks the message up by key.
- Email effects through it are IDEMPOTENT_EXTERNAL.
- EmailQBitProducer registers it as target "email" when durable jobs are
enabled (EmailJobEffectTarget.register).
- docs/DURABLE-JOBS.md and the README describe declaring and emitting email
effects.
verify: 301 tests (14 new), checkstyle clean, coverage 95.4% / 100%.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Declare a named foreign key for every join and table possible-value field
between the ten email tables, plus suppression.source_message_id. Owned
rows cascade, providers/brands/templates with history are RESTRICT, and
optional pointers (template versions, sender address, suppression sources)
are SET NULL so message retention keeps working. The provider delete check
also covers attempts, events and inbox rows. The upgrade script quarantines
orphans before adding the keys; a Testcontainers guardrail test fails when
a new relation has no key.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EmailApiReadiness carries failedChecks (EmailApiReadinessCheck) next to
the plain reasons, so callers such as qbit-marketing can tell a missing
unsubscribe key from a missing provider without parsing text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EmailApi.sendOnce(request, effectKey) with EmailApiEffectOutcome and
EmailApiEffectResult, lookups by idempotency key and RFC Message-ID, and
rfcMessageId on EmailApiMessage, so other qbits have one public surface.
EmailEffects and its types stay as internal, deprecated delegates; the
durable-jobs guide, README and DESIGN 2.5 point at EmailApi.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PhiCanaryEgressTest checks that no five-character window of the canary
appears in any output. The canary's random part was a hex UUID, so a window
could match a SHA-256 body hash or a Message-ID by chance (CI hit "ebf93" in
a body hash). The random part is now mapped from hex to the letters g-v, so a
match can only mean the canary really leaked.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
com.kingsrook.qbits.email.api is the stable contract for other qbits:
EmailApi (isInstalled, send, ensureTemplate, message lookups by id and
idempotency-key prefix with metadata only, sender addresses, default
provider, readiness per category) with its own request, result,
template, message and readiness types. A reflection test keeps internal
types out of every public signature. The README and DESIGN 2.5 document
the two supported routes: core SendMessageAction with the qbitEmail
provider for plain mail, and the api package for the rest; internal
packages are not API.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
For the durable jobs outbox (QRun-IO/qqq#1191, spec section 2.13):
- Each queued message stores one RFC 5322 Message-ID (email_message.rfc_message_id,
unique), derived from the idempotency key (else a stable per-message seed),
and reuses it on every attempt. SMTP, Postmark, SendGrid and Mailgun send it.
SES receives it in the raw MIME but replaces it; this is documented, and
X-QQQ-Email-Id stays on every transport.
- EmailEffects.send(request, effectKey) hands an email to qbit-email's outbox
exactly once per key: QUEUED_OR_DUPLICATE, or REFUSED (suppressed or
invalid; never retried).
- findByIdempotencyKey / findByRfcMessageId look an email up for a reconcile.
- docs/DURABLE-JOBS.md has the outcome mapping and the binding class to add
when QQQ RC.7 ships (EmailJobEffectTarget implements core's EffectTarget;
no SNAPSHOT dependency now).
- Postgres upgrade SQL for existing installs; checkstyle now also covers test
sources (the repo standard), with the existing violations fixed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
email_provider_sender_address (child of the provider; admin-only;
domain, uniqueness and single-default checks). Sends may name a sender
row (withFromAddressId) or match one by text; rows belong to the
resolved provider, the default row wins, and the provider's from
address stays the fallback. Message rows record from_address_id.
Contingent possible-value filters: fromAddressId by providerId on both
send processes, on Send Test Email (seeded from the acted-on provider)
and on email_message; message ids on attempts and events by provider;
suppression source event by source message. One test per pair.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Webhook inbox rows apply matched events independently; unmatched
events retry, then are skipped with a note instead of failing the row.
- Notification and marketing messages are never deleted by retention,
so unsubscribe links keep working; their bodies are still cleared.
- Events only suppress recipients of the matched message; an SES
bounce without recipients no longer suppresses every destination.
- SNS notifications outside a 1 h / +5 min window are refused, and
failed certificate fetches are cached for 5 minutes.
- EmailTemplateDefinition and EmailTemplates.ensure let other qbits
register their templates once without overwriting edits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeps the polished home layout with phase (c)'s event-backed metrics.
Also fixes unsubscribe privacy: a message with an unsubscribe link goes
to exactly one recipient, its token binds that address, and the handler
suppresses only that address (DESIGN 8.2).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase (c) of docs/DESIGN.md: the email_webhook_inbox and email_event
tables; a /qqq/hooks/email route provider with SES (SNS signature and
certificate host rules, subscription confirmation), Postmark (basic
auth), SendGrid (ECDSA) and Mailgun (HMAC with replay protection)
verification into a durable inbox; a claim-safe inbox processor that
maps provider events to email_event rows, message status and
suppressions; RFC 8058 one-click unsubscribe with a confirmation page;
the Reprocess action; and event-backed home metrics.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Key id from QQQ_AUDIT_HMAC_KEY_ID (default env1), canonical values
through ValueUtils, String.valueOf for record keys, and core's verify
argument order. A test pins the stand-in to core's published context
vector (QRun-IO/qqq#1182).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Number-first tiles with plain labels, bar charts for sends per hour and
suppressions added, a compact recent-messages table that stacks on
phones, compact UTC dates, plain provider status words, record labels
for versions, messages and providers, and dark-mode button colours in
the preview that pass 4.5:1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Template sends keep the template's category.
- Render budget (10,000 iterations, 1 MiB), nesting 8, linear parsing.
- URL attributes in HTML and MJML accept only http, https or mailto;
unquoted attribute expressions are refused.
- MJML includes refused and disabled; the compiler runs with PATH only.
- Record variables load only referenced fields; records without a
classification source are tokenized in snapshots.
- Approved templates keep their brand; brand URLs are https and image
hosts are restricted for PHI mail.
- Viewers never trigger an MJML compile from the preview.
- Button links match a single link.
- PHI ciphertexts are bound to table, column and message (AES-GCM AAD).
- EmailDemoServer (test scope) seeds 24 hours of real traffic for
screenshots.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase (b) of docs/DESIGN.md: HTTP JSON and MIME transports over
java.net.http with fixed HTTPS endpoints (Mailgun US and EU), error
mapping to permanent, transient (with Retry-After) and provider-level
failures, tracking flags and message streams, per-kind validation and
env-name allowlists, the Gmail SMTP preset, and docs/PROVIDERS.md.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase (a) part 2 of docs/DESIGN.md: the variable engine with escaping,
if/each and fallbacks; variable schemas; Markdown in the branded
responsive layout with dark-mode colours and contrast checks; HTML and
MJML kinds (MJML through a pluggable compiler at activation); versions
with New Version, Activate Version and Approve For PHI; templated sends
with record variables read as the sender; the classification stand-in
(core #1142); PII/PHI refusal; redacted variable snapshots with
ClassifiedValueTokens-shaped tokens and encrypted PHI bodies (stand-ins
for core #1161); the secure-message built-in; the preview widget; the
home dashboard; contingent possible values; and the canary-PHI egress
test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- email.send no longer implies email.view.
- Provider-level failures (missing or refused credentials, SES account
errors) keep messages waiting without spending their retry budget and
mark the provider unhealthy at once, instead of dead-lettering.
- Unbuildable messages dead-letter at once.
- SMTP sign-in over a plaintext connection is refused (loopback or an
explicit flag excepted).
- One failing message or alert sink no longer stops the batch.
- CR/LF refused in provider sender fields and in MIME headers.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phase (a) part 1 of docs/DESIGN.md: the email_ tables (provider,
message, attempt, template, version, brand, suppression) with Postgres
DDL; provider rows with env-var-name credentials; EmailService with
idempotency keys, suppression and same-transaction enqueue; the
dispatcher with unique-attempt claims, leases, backoff, dead letters,
rate limits and provider health; SMTP (jakarta.mail with auth, TLS and
timeouts) and SES (AWS SDK v2 sesv2 raw) transports; the QBIT_EMAIL
core messaging provider; Resend, Cancel, Send Now and Send Test Email
record actions; scheduled dispatch, maintenance and retention.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apache-2.0 LICENSE and NOTICE, community pointer files, CHANGELOG,
CLAUDE.md and AGENTS.md, Maven wrapper, Checkstyle, dependabot,
CircleCI (qqq-orb 0.6.8, configure-package-install pre-step, GA-only
publish_release), the release-rc caller workflow, and a minimal
EmailQBitProducer and EmailQBitConfig on qbit-build-parent 2.0.0 with
the QQQ 4.1 BOM.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
