Email Studio — Improvement & Growth Plan

Package: capell-app/email-studio · Kind: package · Tier: premium · Product group: Capell Communications · Bundle: communications · Status: Complete

1. Snapshot

Email Studio is the transactional-email backbone for Capell: it registers reusable templates (with locale/site variants), resolves a delivery profile, renders declared {{ variable }} placeholders into a stored snapshot, applies suppression checks, and dispatches a queued SendEmailJob that calls a provider adapter to deliver per-recipient and record outcomes. Provider event webhooks write delivery audit events back into email_events, while the MailTracker-backed admin surface exposes sent-email records, opens, clicks, stored HTML previews, and retention controls. One-click unsubscribe, inbound replies, and native template/profile authoring remain future product depth outside the completed current manifest scope.

Surfaces (declared): admin, frontend, console — in code: routes/web.php exposes tokenized provider-event ingestion, MailTracker owns open/click tracking routes, AdminServiceProvider owns the read-only sent-email admin resource plus settings management, and the queue/console path owns delivery plus retention.
Key Actions: SendEmailAction, DeliverEmailMessageAction, RenderEmailTemplateAction, ResolveEmailTemplateVariantAction, RegisterEmailTemplateAction, CheckEmailSuppressionAction, SuppressEmailAddressAction (src/Actions/).
Models/tables (10 + 1 FK migration): email_profiles, email_templates, email_template_variants, email_messages, email_recipients, email_events, email_replies, email_suppressions, email_template_registrations, email_tracking_tokens (database/migrations/2026_05_10_190847_*, plus 2026_05_21_000001_add_site_foreign_keys_to_email_studio_tables).
Support/infra: EmailVariableRenderer, EmailProfileResolver, EmailProviderRegistry, EmailTemplateRegistry, EmailAddressNormalizer; provider adapters SmtpEmailProviderAdapter, PostmarkEmailProviderAdapter (extends SMTP), FakeEmailProviderAdapter; contract EmailProviderAdapter.
Dependencies: requires capell-app/admin, capell-app/core, capell-app/frontend; supports capell-app/campaign-studio, capell-app/form-builder, capell-app/insights; conflicts none.
Declared capabilities: delivery-audit, mail-tracker-admin, mail-tracker-open-click-tracking, mail-tracker-retention, provider-event-ingestion, provider-normalization-foundation, provider-adapters, suppressions, template-rendering, transactional-email. Reply ingestion, native token tracking, and one-click unsubscribe are not listed as shipped capabilities.
Marketplace summary (verbatim): “Email Studio is Capell’s transactional-email engine: site-scoped reusable templates with safe {{ variable }} rendering, pluggable delivery profiles and provider adapters, suppression enforcement, and a queued, auditable per-recipient send pipeline.”
Screenshots: capell.json promotes the extension card plus four runner-backed sent-email admin captures. docs/screenshots.json declares sent email index/detail and settings-surface capture targets for the Capell screenshot runner.

2. Improvements (existing functionality)

Done/Shipped: Wire EmailStudioHealthCheck to actually run the 4 declared checks. Four diagnostics probe template rendering, delivery adapters, suppressions, and provider event/reply normalization foundations with focused pass/fail coverage. — src/Health/EmailStudioHealthCheck.php, tests/Feature/Health/EmailStudioHealthCheckTest.php — M
Done/Shipped: Persist real Symfony transport message IDs for SMTP/Postmark-over-Symfony sends. SmtpEmailProviderAdapter::send() now reads the returned Laravel/Symfony SentMessage::getMessageId() and maps that provider transport ID onto every delivered recipient instead of fabricating smtp-{message}-{recipient} IDs. PostmarkEmailProviderAdapter inherits the same behavior through its Symfony mailer path. The fake adapter remains deterministic for local/test delivery only. — src/Support/Providers/SmtpEmailProviderAdapter.php, tests/Fixtures/CapturingEmailStudioMailer.php, tests/Unit/EmailStudioDataAndSupportCoverageTest.php — M
Done/Shipped: SendEmailJob retry/backoff/timeout policy. The queued job now has retry/backoff/timeout handling plus a terminal failed() path, and retryable provider exceptions rethrow for the queue instead of immediately marking every recipient permanently failed. — src/Jobs/SendEmailJob.php, src/Actions/DeliverEmailMessageAction.php — M
Done/Shipped: Distinguish transient vs permanent provider failures. Retryable email delivery exceptions now leave the queue in control; permanent provider failures still record recipient/message outcomes through the delivery Action. — src/Actions/DeliverEmailMessageAction.php, src/Exceptions/RetryableEmailDeliveryException.php — M
Shipped 2026-06-05: Batch recipient status writes in the delivery loop. markNewSuppressions now batches newly suppressed recipients, provider failures update by failure-reason bucket, successful recipient provider IDs write through a single upsert, and message status is derived from known delivery counts instead of re-plucking every recipient status. Manifest adminQueryBudget remains 40. — src/Actions/DeliverEmailMessageAction.php — Done
Done/Shipped: CheckEmailSuppressionAction resolves through the container. DeliverEmailMessageAction now calls resolve(CheckEmailSuppressionAction::class)->handle(...), preserving the Action boundary and keeping the suppression check fakeable in tests. — src/Actions/DeliverEmailMessageAction.php — S
Done/Shipped: Body retention is enforced. PruneEmailBodiesAction and capell-email-studio:prune-bodies clear stored rendered HTML/text after the configured retention window, and the package schedules the command daily. — config/capell-email-studio.php, src/Actions/PruneEmailBodiesAction.php, src/Console/Commands/PruneEmailBodiesCommand.php — M
Done/Shipped: MailTracker open/click tracking is active and documented. MailTracker injects the tracking pixel and rewrites links according to EmailStudioSettings; the package disables MailTracker’s bundled Blade admin route and exposes records through Capell’s Filament sent-email resource. Legacy top-level track_opens / track_clicks keys are documented as compatibility flags. — src/Actions/ApplyMailTrackerSettingsAction.php, src/Filament/Resources/SentEmails/SentEmailResource.php, docs/templates-and-providers.md — L
PostmarkEmailProviderAdapter is SMTP-in-disguise — it only overrides mailerName() to 'postmark'; it does not use the Postmark API, capture Postmark message IDs, or verify Postmark webhook signatures. Buyers reading “provider adapters” will expect a real Postmark integration. Either build it on the Postmark HTTP API or rename it to clarify it is “Postmark-over-Symfony-mailer”. — src/Support/Providers/PostmarkEmailProviderAdapter.php — M
EmailProfileResolver default-provider ordering is partly inert — it orders by provider = default_provider but still requires is_default = true; if multiple defaults exist across scopes the secondary ordering rarely matters, and there’s no guard against >1 is_default per scope. Add a partial unique index or resolver tie-break test. — src/Support/EmailProfileResolver.php — S
Locale fallback is opaque — ResolveEmailTemplateVariantAction resolves “requested or current locale before fallbacks” but the fallback chain isn’t documented or configurable (no default-locale config key). Document and make the fallback locale a config value. — src/Actions/ResolveEmailTemplateVariantAction.php — S

3. Missing Features (gaps)

Done/Shipped: provider webhook + event ingestion. POST /mail/provider-events/{token} resolves EmailProfile.webhook_endpoint_token_hash, validates X-Capell-Email-Studio-Signature when provider_settings.webhook_secret is configured, normalizes payloads through the profile provider adapter, writes idempotent EmailEvent rows through RecordProviderEventAction, and updates matching recipient statuses/timestamps for sent/delivered/bounced/complained/opened/clicked/replied/failed events. — routes/web.php, src/Http/Controllers/ProviderWebhookController.php, src/Actions/RecordProviderEventAction.php, src/Actions/ResolveProviderWebhookProfileAction.php, src/Actions/ValidateProviderWebhookSignatureAction.php, tests/Feature/ProviderWebhookControllerTest.php
Inbound reply ingestion. email_replies, EmailReply, InboundEmailReplyData, and normalizeInboundReply() exist but are never wired to a route/action. “Replies” in the summary is currently fictional. — table-stakes.
Done/Shipped: MailTracker open/click tracking endpoints. The package configures MailTracker’s pixel and signed redirect tracking routes, maps MailTracker to package-owned SentEmail / SentEmailUrlClicked models, and exposes the tracked records in Capell admin. The email_tracking_tokens table remains reserved for future native Email Studio message tracking. — table stakes closed for current manifest scope.
Unsubscribe / suppression self-service + List-Unsubscribe header. Suppressions can only be created via SuppressEmailAddressAction server-side. No public one-click unsubscribe route, no signed unsubscribe token, no List-Unsubscribe/List-Unsubscribe-Post headers on outbound mail. This is now effectively mandatory for bulk senders (Gmail/Yahoo 2024 rules). — table-stakes.
Done/Shipped: Admin sent-email surface. SentEmailResource provides a read-only Capell Filament table and detail page for MailTracker sent-email records, opens, clicks, headers, stored HTML previews, and tracked URL click rows; EmailStudioSettingsSchema manages tracking, content storage, queue, and retention settings. Native template/profile authoring remains future depth outside the current manifest scope. — table-stakes for delivery visibility closed.
Done/Shipped: bounce/complaint handling loop. RecordProviderEventAction now calls SuppressEmailAddressAction for bounced and complained provider events, creating site-scoped provider-event suppressions for the affected recipient after the event is recorded. — src/Actions/RecordProviderEventAction.php, tests/Feature/ProviderWebhookControllerTest.php
Scheduling / send-at. SendEmailData has no sendAt; SendEmailJob dispatches immediately. No delayed/scheduled transactional sends. — differentiator.
A/B testing of variants. email_template_variants exists and could host A/B, but ResolveEmailTemplateVariantAction only picks by site+locale+active, with no split assignment, weighting, or winner tracking. — differentiator.
Done/Shipped: Delivery/open/click visibility. The sent-email admin resource surfaces MailTracker opens, clicks, clicked URLs, and stored content state. Deeper aggregate delivery dashboards and Insights feed remain future reporting depth. — differentiator.
Idempotency keys for sends. No dedupe on (templateKey, triggeredByType, triggeredById) — a double-fired listener sends twice. — table-stakes for transactional reliability.
Attachments & inline images. SendEmailData/adapters support neither attachments nor embedded images. — table-stakes for many transactional emails (receipts, tickets).
Done/Shipped: webhook endpoint verification. Provider events require a per-profile token whose SHA-256 hash is stored on email_profiles.webhook_endpoint_token_hash; profiles can also set provider_settings.webhook_secret to require X-Capell-Email-Studio-Signature HMAC validation over the raw request body. Provider-specific timestamp tolerance remains future depth for real HTTP adapters such as Postmark API webhooks; webhook_tolerance_seconds is still unused. — table-stakes (security).

4. Issues / Risks

Closed: Health checks are functional. EmailStudioHealthCheck now probes the declared template-rendering, provider-delivery, suppression, and provider-event foundation checks with focused coverage. — src/Health/EmailStudioHealthCheck.php, tests/Feature/Health/EmailStudioHealthCheckTest.php.
Closed: Manifest surfaces align with shipped behavior. admin is backed by the sent-email resource and settings surface, frontend is backed by tokenized provider webhooks plus MailTracker tracking routes, and console is backed by delivery/retention commands. The manifest still avoids advertising replies, one-click unsubscribe, or native Email Studio template/profile authoring as shipped. — capell.json.
Dead schema + Data objects = maintenance debt is shrinking. EmailEvent and ProviderWebhookEventData now have a real write path through provider-event ingestion. EmailReply, EmailTrackingToken, and InboundEmailReplyData still await consuming routes/actions. — src/Models/EmailEvent.php, src/Models/EmailReply.php, src/Models/EmailTrackingToken.php.
Closed: Queue resilience gap. SendEmailJob now owns retry/backoff/timeout behavior and terminal failure recording, while retryable delivery exceptions rethrow for the queue. — src/Jobs/SendEmailJob.php, src/Actions/DeliverEmailMessageAction.php.
Closed: Multi-recipient delivery write amplification reduced. Recipient statuses now update by suppression/failure bucket and provider IDs write through a single upsert, keeping the current manifest query budget realistic for the package’s supported send path. — src/Actions/DeliverEmailMessageAction.php.
Closed: Rendered-body retention is enforced. PruneEmailBodiesAction and the scheduled prune command clear stored rendered bodies according to body_retention_days. — src/Actions/PruneEmailBodiesAction.php, src/Console/Commands/PruneEmailBodiesCommand.php.
Suppression hashing is unsalted SHA-256. EmailAddressNormalizer::hash() is hash('sha256', lowercased-email). Email address space is enumerable, so a leaked email_suppressions table is trivially reversible via rainbow tables. Consider a keyed HMAC (app-key-derived) if these hashes are meant to protect addresses. — src/Support/EmailAddressNormalizer.php.
Public-output safety. Provider webhook routes return JSON/no-content responses only, MailTracker tracking routes do not render Email Studio admin HTML, and the package still has no public Blade surface. Future unsubscribe/reply routes must keep the same no-admin-output boundary. — routes/web.php.
Reply test coverage is still thin relative to future claims. Tests cover send/deliver/suppression/render/resolve/migrations/relationships and provider-event ingestion. normalizeInboundReply is still only asserted as a pure transformer because inbound reply ingestion has not shipped. — tests/Unit/EmailStudioDataAndSupportCoverageTest.php.
i18n half-done. Enum labels resolve through __('capell-email-studio::generic.statuses.*') (good), but there is no per-recipient/per-message language column on the message itself and locale fallback is undocumented. Translations only ship en. — src/Enums/EmailMessageStatus.php, resources/lang/en/.
Release notes. CHANGELOG.md should keep tracking future product-depth slices, but the current implementation plan is closed by code, manifest, and test evidence.

Test coverage map (what IS covered):

Unit: template registration upsert; variable render (escaping + missing-variable modes, preview vs production); variant resolution (site/locale/fallback); Data/enum/normalizer coverage; SMTP delivery happy-path + provider-id mapping; adapter registry + health metadata; registry persistence pre/post migration; service-provider metadata.
Integration: deliver (suppression recheck, double-claim guard, stale-claim reclaim); suppression check by hash+scope; send (queued send + cross-site rejection); migrations create tables; model relationships.
What ISN’T covered: inbound reply ingestion, one-click unsubscribe flow, Postmark HTTP API behavior, idempotency/dedupe, scheduled sends, attachments, native template/profile authoring, and aggregate delivery dashboards. These are future depth rather than current manifest blockers.

5. Marketplace & Selling

Critique. The capell.json marketplace summary and composer description now scope to what ships today: safe template rendering, delivery profiles and adapters, suppression enforcement, queued delivery, per-recipient send audit, provider event ingestion, and MailTracker-backed sent-email admin/tracking. Keep the guard test in place so replies and unsubscribe do not reappear in buyer-facing metadata until those flows ship.

Improved 1-sentence summary (honest to current code):

Email Studio is Capell’s transactional-email engine: site-scoped reusable templates with safe {{ variable }} rendering, pluggable delivery profiles and provider adapters, suppression enforcement, and a queued, auditable per-recipient send pipeline.

Improved 3–4 sentence description:

Email Studio gives every Capell site a reliable transactional-email core. Define reusable, locale- and site-scoped templates that render through a deliberately safe placeholder engine (HTML-escaped, missing-variable-strict in production), then send through delivery profiles backed by pluggable provider adapters. Every send is rendered to an immutable snapshot, screened against site and global suppression lists, and delivered via a queue job that records per-recipient outcomes for support and audit. Provider event webhooks write delivery events back into the audit trail, while the MailTracker-backed admin surface exposes sent-email records, opens, clicks, stored HTML, and retention controls.

Screenshot/media status. capell.json promotes the extension card plus four runner-backed sent-email admin captures. docs/screenshots.json declares sent email index/detail and settings-surface capture targets; the settings target remains runner evidence until the shared settings page reliably exposes the email_studio group.

Pricing/tier/bundle positioning. premium tier in the communications bundle is now defensible for the current scope: operators get the send pipeline, provider event ingestion, suppression enforcement, sent-email admin visibility, open/click tracking, and retention controls. Cross-sell is strong: it already supports campaign-studio (bulk/marketing sends can reuse templates, profiles, suppressions), form-builder (the docs’ canonical example is forms.confirmation), and insights (future aggregate delivery/open/click metrics). Position Email Studio as the shared sending substrate that those three plug into.

Top differentiators / value props / target buyer.

Differentiators: site-scoped (global vs site:N) templates+suppressions+profiles in one model; immutable rendered snapshot for support reproducibility; provider-agnostic adapter contract; safe-by-default render engine (smaller than Blade, no template injection).
Target buyer: Capell agencies/operators running multi-site installs who need branded transactional mail (form confirmations, account/order notifications) with auditability and per-site control — without bolting on a third-party ESP SDK per project.

8–12 keywords/tags: transactional-email, email-templates, email-suppressions, delivery-profiles, provider-adapters, smtp, postmark, email-audit-log, multi-site-email, queued-email, unsubscribe, bounce-handling.

Completed 2026-06-08. Every current manifest-backed roadmap row is closed: Email Studio now ships functional health checks, retry-aware queued delivery, provider message IDs, body-retention pruning, batched recipient outcome writes, provider webhook ingestion with optional HMAC validation, hard-bounce/complaint suppression, MailTracker open/click tracking, a read-only sent-email admin resource, settings/retention controls, and runner-backed Marketplace media. One-click unsubscribe, inbound replies, Postmark HTTP API depth, scheduled sends, attachments, native template/profile authoring, and aggregate delivery dashboards remain future product-depth candidates rather than active completion blockers.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
✅ Shipped 2026-06-04: Align manifest/composer summary + capabilities to shipped reality. Evidence: manifest/composer/README/docs copy now sell the shipped send/audit pipeline and provider normalization foundations, with tests guarding against replies/events/webhooks/tracking/unsubscribe being advertised as done.	Done	S	High	§5, §4
✅ Shipped 2026-06-04: Implement `EmailStudioHealthCheck` to run the 4 declared checks. Evidence: four diagnostics now probe template rendering, delivery adapters, suppressions, and provider event/reply normalization with focused pass/fail tests.	Done	M	High	§2, §4
✅ Shipped: Add `SendEmailJob` retry/backoff/timeout + `failed()`; split transient vs permanent failures	Done	M	High	§2, §4
✅ Shipped 2026-06-05: Capture real provider message IDs for SMTP/Postmark-over-Symfony sends. Evidence: SMTP maps `SentMessage::getMessageId()` to delivered recipients with fixture coverage; fake IDs remain local/test only.	Done	M	High	§2, §3
✅ Shipped: Enforce `body_retention_days` via scheduled prune command (PII)	Done	M	High	§2, §4
✅ Shipped 2026-06-05: Batch recipient status writes in `DeliverEmailMessageAction` (query-budget)	Done	M	Med	§2, §4
Done/Shipped: Provider webhook ingestion route + `RecordProviderEventAction` writes `email_events` and updates recipient status through tokenized endpoint and optional HMAC verification	Done	L	High	§3, §4
One-click unsubscribe: signed token route + `List-Unsubscribe` headers + self-service suppression	Future	M	High	§3, §4
Done/Shipped: Auto-suppress on hard bounce / complaint once events ingest	Done	M	High	§3
Done/Shipped: MailTracker sent-email admin surface, settings, tracking controls, and runner-backed sent-email screenshots	Done	L	High	§3, §5
Real Postmark adapter (API + message-id + webhook verify) or rename to avoid over-promising	Future	M	Med	§2, §3
Inbound reply ingestion route + `RecordInboundReplyAction` (writes `email_replies`)	Future	M	Med	§3
Done/Shipped: MailTracker open/click tracking routes, pixel injection, link rewriting, package-owned models, and Capell admin read surface	Done	L	Med	§2, §3
Scheduled sends (`sendAt`) + idempotency keys + attachments/inline images	Future	M	Med	§3
Native template/profile/suppression authoring and aggregate delivery dashboards	Future	L	Med	§3, §5