Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/feature-decisions/email-marketing-decision-report.md
T
2026-07-08 16:15:37 +02:00

23 KiB

Email Marketing Decision Report

Decision

Decision: extract-plugin.

Email Marketing and Newsletter are optional plugin surfaces. They are not boilerplate Core because campaign management, subscriber/audience selection, sender configuration, tracking, and marketing consent rules are product-specific. They are also not immediate-removal targets because the current implementation has real campaign, sender, outbound-email, route, schema, translation, and CRM-contact dependencies that must be unwound atomically.

The canonical strategy is to keep Email Marketing as a plugin candidate that currently depends on CRM contacts. A future extraction must either bundle Email Marketing with the CRM plugin, declare an explicit dependency on the CRM plugin, or introduce a plugin-owned audience/list abstraction before CRM contacts or CRM entities are removed from Core.

This decision is deliberately narrower than the Email Sequences and marketing-outbound foundations. Email Marketing means the CRM-contact campaign surface under apps/web/app/modules/emailMarketing and the email-marketing admin/tenant routes. Email Sequences are documented in docs/features/email-sequences.md as foundation/admin-preview work with production follow-ups. The generic marketing-outbound handler is documented in docs/features/marketing-funnel.md as an unbootstrapped general handler foundation.

This report is documentation-only. It records the decision and safe execution order for later extraction/removal work; it does not change runtime behavior.

Scope

In scope for this decision:

  • Classify Email Marketing and Newsletter as optional plugin surfaces with action extract-plugin.
  • Keep Email Marketing scoped to CRM-contact campaign management, not the Email Sequences foundation/admin-preview surfaces.
  • Preserve transactional mail as Core and keep marketing mail outside that Core boundary.
  • Document current Email Marketing routes, modules, database/schema surfaces, command/i18n references, and manifest/docs dependencies.
  • Record the current CRM contact/audience dependency and the required extraction choices before CRM removal.
  • Define an atomic execution plan and a static verification plan for later tasks.

Out of scope for this decision:

  • Removing apps/web/app/modules/emailMarketing, routes, Prisma models, translations, command entries, or manifests in this slice.
  • Migrating CRM, replacing contacts with a new audience model, or changing campaign send behavior in this slice.
  • Moving provider secrets or adding runtime plugin packaging mechanics in this slice.
  • Changing transactional email behavior in apps/web/app/modules/emails, apps/web/app/application/emails, apps/web/app/utils/services/emailService.ts, or packages/mail.
  • Reclassifying Email Sequences as an Email Marketing plugin candidate or claiming production delivery before seed data, stats aggregation, E2E, Mailjet delivery evidence/reconciliation, and scheduler/deploy evidence follow-ups land.
  • Bootstrapping the generic marketing-outbound subscriber or treating MARKETING_WEBHOOKS_ENABLED as evidence that Slack, Discord, Mailchimp, HubSpot, Brevo, or custom webhook delivery is active.

Current Code Surfaces

The current known Email Marketing surfaces are:

Surface Current role Future handling
apps/web/app/modules/emailMarketing Email Marketing module root for campaign, sender, outbound-email, and send services. Move into an Email Marketing plugin or remove after routes, schema, translations, and CRM dependency are handled.
apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts Main campaign service. Imports CrmService and ContactDto, loads contact views, validates marketing subscribers, performs contact variable replacement, sends tests and campaigns, and writes outbound status. Plugin-owned service. Must not remain in Core while importing CRM unless Email Marketing and CRM are bundled or dependency-gated.
apps/web/app/modules/emailMarketing/db/emailSender.ts Email sender persistence surface. Stores provider, stream, API key, from/reply-to fields, and optional tenant ownership through EmailSender. Plugin-owned settings/storage surface; extraction must preserve secret ownership rules and migration.
apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts Campaign persistence and campaign-recipient composition. Plugin-owned persistence surface tied to Campaign and OutboundEmail schema.
apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts Outbound email tracking persistence for previews, sends, delivery, opens, clicks, bounces, spam complaints, and unsubscribes. Plugin-owned persistence and analytics surface.
apps/web/app/routes/admin/email-marketing.tsx Admin Email Marketing layout route. Validates CRM entities through CrmService.validate(null) and exposes Overview, Campaigns, Activity, and Senders navigation. Plugin admin route shell; CRM validation must be replaced by declared plugin dependency or audience validation.
apps/web/app/routes/admin/email-marketing/* Admin nested Email Marketing routes for overview/campaign/activity/sender workflows. Move/delete atomically with admin layout and module services.
apps/web/app/routes/app.$tenant/email-marketing.tsx Tenant Email Marketing layout route. Requires tenantEmailMarketing feature flag, validates CRM through CrmService.validate(tenantId), and exposes tenant navigation. Plugin tenant route shell; must be disabled clearly when plugin or CRM/audience dependency is unavailable.
apps/web/app/routes/app.$tenant/email-marketing/* Tenant nested Email Marketing routes for tenant campaign/activity/sender workflows. Move/delete atomically with tenant layout and feature-gate behavior.
prisma/schema/email.prisma Defines inbound email models plus Email Marketing models EmailSender, Campaign, OutboundEmail, OutboundEmailOpen, and OutboundEmailClick. OutboundEmail.contactRowId references CRM contact rows through generic Row. Split or migrate plugin-owned schema. Preserve Core transactional mail boundary and avoid deleting inbound/system mail accidentally.
apps/web/app/services/command-registry/commandRegistry.ts Shared command registry named by the slice contract as a possible Email Marketing/CRM command visibility surface. Future verifier/extraction must confirm whether Email Marketing commands exist and move/remove them through plugin command registration if present.
apps/web/public/locales/en/translations.json Contains Email Marketing strings such as emailMarketing.title and sender labels used by routes. Move plugin strings with plugin UI or remove only when UI is removed.
apps/web/public/locales/de/translations.json German Email Marketing translation counterpart. Move plugin strings with plugin UI or remove only when UI is removed.
docs/feature-manifests/plugin-candidates.json Lists email-marketing as a plugin candidate with module/routes/emails code areas and broader plugin extraction rules. Keep consistent with this report and later split into a dedicated plugin manifest if extraction begins.
docs/feature-manifests/transactional-mail.json Defines transactional mail as Core and explicitly says newsletter/marketing abstractions may move to plugins. Must remain the boundary source for Core mail. This report must not reclassify marketing mail as transactional Core.
docs/feature-decisions/crm-decision-report.md Canonical CRM decision. It identifies Email Marketing as the most important downstream CRM dependency. Email Marketing extraction/removal order must follow this CRM dependency contract.

Additional inventory evidence:

  • docs/feature-inventory.md classifies Email Marketing/Newsletter as Optional/Plugin and Core mail as Transactional Email only.
  • docs/feature-manifests/plugin-candidates.json includes apps/web/app/modules/emailMarketing, apps/web/app/routes/admin/email-marketing*, and apps/web/app/routes/app.$tenant/email-marketing* under the email-marketing component.
  • docs/feature-manifests/transactional-mail.json keeps password reset, invitation, verification, and system email in Core while allowing Email Marketing and Newsletter abstractions to move to plugins.
  • docs/features/email-sequences.md keeps Email Sequences separate as foundation/admin-preview work gated by MARKETING_SEQUENCES_ENABLED, with production delivery blocked on explicit follow-ups.
  • docs/features/marketing-funnel.md keeps the general marketing-outbound handler separate as a shipped foundation that is not bootstrapped from apps/worker/src/index.ts.

Couplings

CRM contacts and audience selection

apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts directly imports CrmService and ContactDto from ~/modules/crm/services/CrmService. Campaign drafts call EntityViewsApi.get() for entity name contact, load contact row IDs, call CrmService.getContactsInRowIds(), and reject campaigns when contacts are missing or not marked as marketingSubscriber. Contact previews and campaign sends call CrmService.getContact() and use contact fields for variable replacement.

This makes CRM the current audience provider for Email Marketing. CRM cannot be removed from Core first unless Email Marketing is also extracted with CRM, is disabled behind a clear CRM-plugin dependency, or receives a plugin-owned audience/list abstraction that replaces CRM contacts and the marketingSubscriber contact field.

Rows/entities runtime

Campaign recipients use OutboundEmail.contactRowId in prisma/schema/email.prisma, and that field relates to generic Row. This ties marketing recipients to the rows/entities runtime and, in practice, to CRM contact rows. Future extraction may keep rows/entities as Core infrastructure, but Email Marketing must own or declare the contact/audience semantics that sit on top of rows.

Routes and feature gating

apps/web/app/routes/admin/email-marketing.tsx and apps/web/app/routes/app.$tenant/email-marketing.tsx are layout routes with nested route directories. Both validate CRM before rendering. The tenant route also checks appConfiguration.app.features.tenantEmailMarketing and redirects when tenant Email Marketing is disabled. Future plugin packaging must preserve clear disabled-state behavior and avoid leaving routable pages that fail because CRM entities are missing.

Sender, provider, and outbound services

Email Marketing owns sender configuration, campaign composition, outbound email records, tracking records, and broadcast send calls. This is a marketing-send surface, not a Core transactional mail surface. Future extraction must move these pieces together so Core password reset/invitation/system email remains independent from marketing campaign providers and tracking.

Commands, navigation, and translations

Routes use emailMarketing.title and emailMarketing.senders.plural translation keys and email/crm icon navigation. apps/web/app/services/command-registry/commandRegistry.ts is the shared command-registration surface that must be audited for Email Marketing or CRM-dependent entries during extraction. Translation keys in apps/web/public/locales/en/translations.json and apps/web/public/locales/de/translations.json should move with plugin UI or be removed only when all plugin UI is removed.

Documentation and manifests

docs/feature-inventory.md, docs/feature-manifests/plugin-candidates.json, docs/feature-manifests/transactional-mail.json, and docs/feature-decisions/crm-decision-report.md together define the boundary: Email Marketing is a plugin candidate, CRM is a plugin candidate, transactional mail remains Core, and CRM contacts currently provide the Email Marketing audience. Future implementation and verification must keep those sources consistent.

docs/feature-manifests/plugin-candidates.json must not use the email-sequences admin-preview foundation or the unbootstrapped marketing-outbound handler as evidence that Email Marketing has already been extracted. Email Sequences and marketing-outbound may interact with marketing queues, but they are separate status surfaces: Email Sequences are foundation/admin-preview with production followups, while marketing-outbound is a general handler foundation until a worker bootstrap wires its subscriber.

Sender Secrets and Provider Boundary

Email Marketing sender credentials are plugin-owned marketing credentials, not Core transactional-mail credentials. prisma/schema/email.prisma defines EmailSender.apiKey, provider, stream, from-address, reply-to, tenant, campaign, and outbound-email relations. docs/feature-manifests/plugin-candidates.json states that plugin provider secrets must be admin/platform-owned unless explicitly tenant-owned, while docs/feature-manifests/transactional-mail.json states transactional mail provider API keys are platform/admin-owned and never tenant-owned.

Future extraction must therefore make ownership explicit:

  1. Marketing sender API keys must move with the Email Marketing plugin and be encrypted/stored according to the platform's secret-storage standard.
  2. Tenant-scoped senders may exist because EmailSender.tenantId is optional, but tenant ownership does not imply arbitrary tenant access to raw provider secrets.
  3. Transactional mail settings for password reset, invitation, verification, and system email remain Core and must not be reused implicitly for bulk marketing campaigns.
  4. Marketing sends, campaign tracking, unsubscribe handling, opens, clicks, bounces, and spam complaints are plugin responsibilities.
  5. A future verifier must fail if the report or manifests blur transactional mail and marketing mail boundaries.

Schema and Data Impact

prisma/schema/email.prisma contains both inbound/general email models and marketing campaign models. The marketing-owned schema impact is:

  • EmailSender stores sender/provider configuration, API key, optional tenant ownership, and relations to campaigns/outbound emails.
  • Campaign stores campaign metadata, content, status, sender relation, optional tenant ownership, and recipient relation.
  • OutboundEmail stores each recipient/send record, optional campaign relation, contactRowId, email address, sender, preview flag, errors, sent/delivery/bounce/spam/unsubscribe timestamps, and open/click relations.
  • OutboundEmailOpen and OutboundEmailClick store tracking events.
  • OutboundEmail.contactRowId links to Row, which currently represents CRM contacts selected through contact entity views.

Future extraction must choose one data strategy before removing CRM contact rows:

  1. Bundle with CRM: keep contactRowId and contact variables because CRM remains installed with Email Marketing.
  2. Depend on CRM plugin: declare the dependency and fail clearly when CRM is not enabled.
  3. Own audience/list data: introduce plugin-owned audience, subscriber, list, consent, and merge-field tables or row templates, then migrate campaigns/outbound records away from direct CRM contact assumptions.

Data migration must preserve campaign history, outbound delivery/tracking history, unsubscribe state, and sender configuration. Existing rows should not be silently deleted when a plugin is disabled.

CRM Audience Decision

The current audience decision is explicit: Email Marketing depends on CRM contacts today. EmailMarketingService.ts uses CRM contacts as campaign recipients, enforces marketingSubscriber, replaces variables from CRM contact/company fields, and rejects non-contact campaign recipients. The CRM decision report also says CRM extraction must audit Email Marketing first.

Future extraction must pick exactly one path before CRM removal:

  1. Bundle path: extract Email Marketing and CRM together as a vertical plugin where CRM contact rows remain the canonical audience.
  2. Dependency path: extract Email Marketing separately but declare CRM as a required plugin dependency; disabled or missing CRM must produce a clear unavailable-plugin status instead of route/runtime errors.
  3. Audience abstraction path: create an Email Marketing-owned audience/list/subscriber abstraction with consent fields, import/sync hooks, and merge-field support; migrate campaign creation and send flows away from CrmService and contactRowId before CRM is removed.

Until one path is implemented, Email Marketing must not be treated as standalone Core and CRM must not be deleted ahead of Email Marketing.

Execution Plan

Future Email Marketing extraction/removal work must run in this atomic sequence:

  1. Decision/report: land this extract-plugin report and the static verifier before runtime changes.
  2. Manifest/docs alignment: update docs/feature-inventory.md, docs/feature-manifests/plugin-candidates.json, and any dedicated Email Marketing manifest so they point to this canonical report and agree with docs/feature-manifests/transactional-mail.json.
  3. CRM audience decision: choose bundle, dependency, or audience abstraction. Do not remove CRM contacts, CrmService, or CRM entity templates before this choice is implemented.
  4. Route/module packaging: move or remove apps/web/app/modules/emailMarketing, apps/web/app/routes/admin/email-marketing.tsx, apps/web/app/routes/admin/email-marketing/*, apps/web/app/routes/app.$tenant/email-marketing.tsx, and apps/web/app/routes/app.$tenant/email-marketing/* in one implementation slice.
  5. Schema migration: move or migrate plugin-owned EmailSender, Campaign, OutboundEmail, OutboundEmailOpen, and OutboundEmailClick ownership while preserving transactional/inbound mail models needed by Core.
  6. Sender secret boundary: migrate marketing sender provider secrets to plugin-owned settings and ensure Core transactional mail credentials remain separate.
  7. Command/navigation/i18n cleanup: remove or plugin-register Email Marketing command entries in apps/web/app/services/command-registry/commandRegistry.ts, route/sidebar visibility, icons, and translation keys in apps/web/public/locales/en/translations.json and apps/web/public/locales/de/translations.json.
  8. Tests/static scans: add focused tests and static checks so Core no longer imports Email Marketing when the plugin is disabled, transactional mail remains available, CRM dependency behavior is explicit, and docs/manifests stay consistent.

Verification Plan

T03 must add a local static verifier, expected at scripts/verify-email-marketing-decision-report.mjs, and a focused test file, expected at scripts/verify-email-marketing-decision-report.test.mjs. The verifier must fail on the negative cases named in this task plan:

  • Missing required heading: Decision, Scope, Current Code Surfaces, Couplings, Sender Secrets and Provider Boundary, Schema and Data Impact, CRM Audience Decision, Execution Plan, Verification Plan, Risks.
  • Missing exact decision token Decision: extract-plugin``.
  • Placeholder drift such as unresolved TODO/TBD placeholders outside explicit verifier-requirement wording.
  • Unresolved required path references for concrete current paths and route directories.
  • Manifest drift between this report, docs/feature-inventory.md, docs/feature-manifests/plugin-candidates.json, docs/feature-manifests/transactional-mail.json, and docs/feature-decisions/crm-decision-report.md.
  • Missing CRM coupling statements for CrmService, ContactDto, contact views, marketingSubscriber, and OutboundEmail.contactRowId.
  • Boundary drift that mixes transactional mail with marketing mail or omits sender API-key ownership.

The verifier should specifically check that this report references the current required surfaces: apps/web/app/modules/emailMarketing, apps/web/app/routes/admin/email-marketing.tsx, apps/web/app/routes/admin/email-marketing/*, apps/web/app/routes/app.$tenant/email-marketing.tsx, apps/web/app/routes/app.$tenant/email-marketing/*, apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts, apps/web/app/modules/emailMarketing/db/emailSender.ts, apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts, apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts, prisma/schema/email.prisma, apps/web/app/services/command-registry/commandRegistry.ts, apps/web/public/locales/en/translations.json, apps/web/public/locales/de/translations.json, docs/feature-manifests/plugin-candidates.json, docs/feature-manifests/transactional-mail.json, and docs/feature-decisions/crm-decision-report.md.

Task-level smoke verification for this report is:

  • test -s docs/feature-decisions/email-marketing-decision-report.md
  • grep -q "Decision: \extract-plugin`" docs/feature-decisions/email-marketing-decision-report.md`

Manual verification for a future runtime extraction should cover:

  • Password reset, invitation, verification, and system emails still work without Email Marketing installed.
  • Email Marketing routes are absent or show a clear disabled-plugin state when the plugin is disabled.
  • Campaign creation and sending either work with the declared CRM dependency or use the new audience/list abstraction.
  • Sender credentials are not exposed to tenants beyond intended administration workflows.
  • Existing campaigns, outbound history, tracking events, unsubscribes, and sender settings remain migratable.

Risks

  • Missing the CRM contact coupling would make later CRM extraction break campaign preview/send flows.
  • Mixing transactional mail with marketing mail would risk breaking password reset, invitation, verification, or system email while removing campaign features.
  • Omitting sender API-key ownership would make plugin extraction unsafe because marketing credentials may be tenant-scoped in data but still require platform-grade secret handling.
  • Removing Email Marketing routes without schema/data migration can leave campaigns, outbound records, tracking data, and sender secrets orphaned.
  • Removing CRM contacts before an audience decision can leave campaigns without recipients and variable replacement without data.
  • Translation, command, sidebar, and route-helper leftovers can keep a removed plugin visible or navigable.
  • Existing tenants may rely on campaign history, unsubscribes, and sender configuration; plugin extraction should include compatibility, export, or migration notes rather than silent data loss.

Update (R-P14C)

HiveGrid ticket R-P14C (2026-06-30) removes the legacy Entity-Builder campaign path under Variante A (remove, do not migrate — the bespoke campaign editor is rebuilt by David/D-KAMP). The typed send engine (CampaignSendService) and typed recipient segments (AK-P14b) already cover sending, so no functionality is lost beyond the old UI shell:

  • apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts deleted (the CrmService/ContactDto/contact-views consumer). The Campaigns list/new/edit routes, components, and the OutboundEmail.contactRowId column rendering were removed; the typed activity log keeps opens/clicks/delivery.
  • The OutboundEmail.contactRowId / Row relation is dropped from prisma/schema/email.prisma; the typed kontaktId field is the recipient link.
  • apps/web/app/modules/crm legacy reader is removed once its last consumer is gone. The file-existence + manifest-code-area assertions for EmailMarketingService.ts were dropped from scripts/verify-email-marketing-decision-report.mjs; the historical coupling references (CrmService, ContactDto, OutboundEmail.contactRowId) are kept.