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>