245 lines
26 KiB
Markdown
245 lines
26 KiB
Markdown
# Marketing-Funnel — Phase 3: Email-Sequence-Engine + Pre-Built-Templates + Statistics
|
|
|
|
> **Status source warning:** this file is historical implementation context
|
|
> with reconciled notes. Use `docs/features/email-sequences.md` as the
|
|
> canonical current status for Email Sequences. Do not infer production mail
|
|
> delivery readiness from this phase plan.
|
|
|
|
**Status:** in_progress (data model + pure engine + 4 template definitions + scheduler foundation + production delayed-step scheduling + bundled sequence renderer + `@toolctrl/mail` Mailjet adapter + signed Mailjet bounce webhook handling + open/click tracking + unsubscribe + worker-bootstrap-wiring + admin UI/CLI + live stats dashboard + stale-lead/trial-expiring runner functions + docs shipped; this is shipped foundation/admin-preview work, not an approved production email-delivery claim, until seed data, statistics aggregation cron, Playwright E2E, delivery webhook production evidence, provider engagement reconciliation beyond the in-repo tracking routes, and scheduled-job registration/deploy evidence land — tracked in Deviations)
|
|
**Task-ID:** #80
|
|
**Phase:** 05
|
|
**Estimated Effort:** 1.5-2 Wochen
|
|
**Owner:** unassigned
|
|
|
|
## Problem
|
|
|
|
_Historical planning problem statement; current shipped/deferred status is summarized in the Status line, Deviations section, and `docs/features/email-sequences.md`._
|
|
|
|
Phase 1+2 erfassen und konvertieren Leads — aber nach Conversion (oder bei Lead-Stagnation) gibt es keinen automatisierten Engagement-Pfad. Konkrete Gaps heute:
|
|
|
|
- Neuer Lead bekommt keine Welcome-Sequence ("Tag 1: Begrüßung, Tag 3: Use-Case, Tag 7: Demo-Einladung")
|
|
- Trial-User dessen Trial in 7 Tagen ausläuft → keine Reminder
|
|
- Lead der vor 60 Tagen captured wurde und nicht konvertiert ist → keine Re-Activation-Versuche
|
|
- Neuer Tenant nach Signup → kein Onboarding-Drip
|
|
- Keine Sichtbarkeit über Open-Rates / Click-Rates der versendeten Mails
|
|
|
|
Konkurrenz-Lösungen (Customer.io, Mailchimp-Journeys, HubSpot-Workflows) machen genau das. Ohne Phase 3 endet der Funnel statisch bei der Conversion — Engagement bleibt komplett manuell.
|
|
|
|
## Depends on
|
|
|
|
- `05-business-features/marketing-funnel-phase-2.md` (#79) — Lifecycle-Events (`lead.captured`, `lead.converted_to_trial`, etc.) als Trigger
|
|
- `05-business-features/marketing-funnel-phase-1.md` (#78) — Lead-Model
|
|
- `05-business-features/feature-flags.md` (#53) — Sequence-Aktivierung global oder pro Tenant
|
|
- `03-scaling-infrastructure/outbox-pattern.md` (#42) — Trigger-Events kommen aus Outbox
|
|
- `03-scaling-infrastructure/worker-queues.md` (#43) — Scheduler-Worker für delayed Email-Jobs
|
|
- `10-compliance-polish/react-email.md` — historische Voraussetzung für Email-Templates. React-Email ist abgeschlossen; aktuelle Produktions-Follow-ups liegen im sequence-spezifischen Renderer und Mail-Adapter, siehe `docs/features/email-sequences.md`.
|
|
- Existierendes transactional-Mail-Provider-Setup — wird konsumiert
|
|
|
|
## Blocks
|
|
|
|
- Nichts kritisches direkt; aber gesamte Marketing-Strategy hängt von Sequences ab für Effekt
|
|
|
|
## Approach
|
|
|
|
Fünf-Komponenten:
|
|
|
|
1. **EmailSequence-Datenmodell** — Sequence-Definition mit Trigger + Steps (delay + template + conditions). Per-Step-Statistik-Aggregate.
|
|
2. **Sequence-Execution-Engine** — Trigger-Event-Handler enqueued `SendEmailJob` pro Step mit delay-from-trigger. Pro Step Conditions evaluiert.
|
|
3. **React-Email-Templates** — Pre-Built Sequence-Templates + reusable Template-Components.
|
|
4. **Unsubscribe-Layer** — Standards-konform List-Unsubscribe-Header + signed-Token-URL.
|
|
5. **Statistics-Dashboard** — Open/Click/Conversion-Rate pro Sequence + per Step.
|
|
|
|
**Begründung der Architektur-Wahl:**
|
|
|
|
- **Sequence-Steps als JSON Array vs separate Tabelle:** für V1 sind Sequences linear (Step 1, 2, 3, ...). JSON-Array reicht + ist schneller zu querien. Wenn V2 Branching/Parallel-Pfade kommen, Schema-Refactor möglich.
|
|
- **Delay als `delayHours` per Step relativ-from-trigger statt absolute Schedule:** ermöglicht generic Re-Use einer Sequence für jeden neuen Lead ohne Date-Math im Definition-Schema.
|
|
- **Conditions per Step (z.B. "nur senden wenn `lead.status != 'unsubscribed'`"):** verhindert Mails an Lost-Leads, ohne ganze Sequence-Cancellation-Logic.
|
|
- **Scheduler-Worker statt Cron:** Cron-Frequency (z.B. alle 5min) wäre für genaue Delays unbrauchbar. Schedulable-Queue (BullMQ-Style mit `delay`-Option) liefert per-Minute-Genauigkeit ohne Cron-Polling.
|
|
- **React-Email für Templates:** Tooling für visuelle Vorschau, Type-Safety, gemeinsame Component-Library mit Transactional-Mails — produktionsreif und in Phase 10 sowieso geplant. Vorziehen ist Kostengünstigste.
|
|
- **List-Unsubscribe-Header:** RFC-8058 + RFC-2369 conform — Gmail/Outlook zeigen Unsubscribe-Button direkt im Email-UI. Reduziert Spam-Reports drastisch (Google PostMaster).
|
|
|
|
## Implementation Steps
|
|
|
|
1. **React-Email-Vorziehung (aus Phase 10)** — falls noch nicht durch: `packages/email/` setup mit React-Email-Renderer, Base-Layout-Component, Footer-Component mit Unsubscribe-Link-Placeholder. Existing transactional-Mail-Service umstellen (Mindestens: 1-2 Mails als Smoke-Test). Detail-MD `10-compliance-polish/react-email.md` als Vorbild — vollständige Implementation dort.
|
|
- Files: `packages/email/` package scaffold
|
|
- Commit: `05/marketing-phase-3: pull react-email forward from phase 10`
|
|
- **Note:** wenn React-Email separat in Phase 10 voll umgesetzt wird, hier nur Stub + Migration-Hinweis
|
|
2. **Prisma-Models** — Current shipped schema uses `EmailSequence`, `EmailSequenceRun`, and `EmailSequenceStepDelivery` in `prisma/schema/emailSequences.prisma`. The original spec names `SequenceEnrollment`, `SequenceEmailLog`, and `SequenceStatistics` are historical placeholders; persisted `SequenceStatistics` remains deferred while the admin dashboard computes live stats from delivery rows.
|
|
- Files: `prisma/schema.prisma`, `prisma/migrations/<ts>_email_sequences/migration.sql`
|
|
- Commit: `05/marketing-phase-3: prisma models for sequences enrollments logs`
|
|
3. **Sequence-Trigger-Worker** — Current shipped worker contract is `apps/worker/src/jobs/email-sequence-trigger.ts`: consumes matching outbox events, persists trigger context into `EmailSequenceRun.stepStateJson`, and starts `EmailSequenceRun` rows idempotently. The runtime now enqueues delayed `email-sequence.step` jobs with stable `email-sequence-step:<runId>:<stepIndex>` ids.
|
|
- Files: `apps/worker/src/jobs/email-sequence-trigger.ts`, Test
|
|
- Commit: `05/marketing-phase-3: sequence trigger handler`
|
|
4. **Sequence-Send-Worker** — Current shipped scheduler foundation is `apps/worker/src/jobs/email-sequence-scheduler.ts` plus `email-sequence-runtime.ts`. It exercises step-runner contracts and killswitch behavior, enqueues delayed steps, renders the bundled sequence templates, and sends through `@toolctrl/mail` when the Mailjet env pair is configured. Missing Mailjet config fails closed.
|
|
- Files: `apps/worker/src/jobs/email-sequence-scheduler.ts`, `apps/worker/src/jobs/email-sequence-runtime.ts`, Tests
|
|
- Commit: `05/marketing-phase-3: sequence send handler with conditions and advance`
|
|
5. **Email-Open/Click-Tracking** — Shipped routes are `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx` (1x1 transparent GIF, Update `openedAt`) and `apps/web/app/routes/email/track-click.$deliveryId.tsx` (Update `clickedAt` if null, safe HTTP(S) redirect). Signed Mailjet bounce/rejection ingress is also shipped. Provider-native delivery/open/click reconciliation beyond these routes remains a production-delivery follow-up.
|
|
- Files: `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx`, `apps/web/app/routes/email/track-click.$deliveryId.tsx`, Tests
|
|
- Commit: `05/marketing-phase-3: email open click tracking`
|
|
6. **Unsubscribe-Layer** — `unsubscribeToken({ leadId?, tenantId?, sequenceId? })` → signed-Token; `/unsubscribe/$token` Route. Action setzt Enrollment-Status `unsubscribed` + Lead-Field `unsubscribedAt`. Confirmation-Page. List-Unsubscribe-Header in jeder Sequence-Mail mit `<mailto:unsubscribe+token@toolctrl.de>, <https://app.toolctrl.de/unsubscribe/token>` (RFC-8058 One-Click-Variante).
|
|
- Files: `apps/web/app/utils/email/unsubscribeToken.server.ts`, `apps/web/app/routes/unsubscribe.$token.tsx`, Test
|
|
- Commit: `05/marketing-phase-3: unsubscribe layer with rfc8058 one-click`
|
|
7. **Pre-Built Sequence-Templates (Definitions + React-Email-Templates)** — vier Standard-Sequences als Seed-Data:
|
|
- **"New Lead Welcome"** (Trigger: `lead.captured`): 5 emails über 14 Tage — Begrüßung (0h), Use-Case-Highlight (Day 2), Customer-Story (Day 5), Demo-Einladung (Day 9), Last-Chance-Offer (Day 14)
|
|
- **"Trial Expiring"** (Trigger: `tenant.trial_expiring`): 3 emails letzte Woche — 7d-vor-Ablauf, 3d-vor, 1d-vor mit Upgrade-CTA
|
|
- **"Lost Lead Re-Activation"** (Trigger: Cron-Job 60d-stale-leads scheint matching trigger): 3 emails über 21 Tage — "Wir vermissen dich", neue Features, exclusive Discount
|
|
- **"New Tenant Onboarding Drip"** (Trigger: `tenant.signup`): 4 emails über 21 Tage — Setup-Checklist, Feature-Tour, Power-User-Tipps, Feedback-Survey
|
|
- Seed-Migration legt Sequence-Rows + Step-Definitionen + Template-Files an
|
|
- Files: `prisma/seed-sequences.ts`, `packages/email/src/templates/sequences/{NewLeadWelcome,TrialExpiring,LostLeadReactivation,OnboardingDrip}/*.tsx`
|
|
- Commit: `05/marketing-phase-3: four pre-built sequence templates`
|
|
8. **Admin-UI für Sequences** — Current shipped route is `/admin/email-sequences`: list, create, edit/toggle, and stats views with JSON step editing. No drag-drop editor, template picker, or visual condition builder shipped.
|
|
- Files: mehrere Route-Files unter `apps/web/app/routes/admin.email-sequences.*`, Components
|
|
- Commit: `05/marketing-phase-3: admin sequence editor and detail view`
|
|
9. **Sequence-Statistics-Aggregation** — Deferred. The current stats view reads live `EmailSequenceRun` / `EmailSequenceStepDelivery` data and computes rates in the admin route. A persisted aggregation cron is still required before larger production datasets.
|
|
- Files: `apps/worker/src/cron/marketing-sequence-aggregate.ts`, Schema-Extension, Test
|
|
- Commit: `05/marketing-phase-3: sequence statistics aggregation cron`
|
|
10. **Statistics-Dashboard** — Current shipped route is `/admin/email-sequences/$id/stats`: per-step scheduled/sent/opened/clicked/bounced/skipped counters plus computed rates. Trend/funnel/top-performing visualizations remain future polish.
|
|
- Files: `apps/web/app/routes/admin.email-sequences.$id.stats.tsx`, Chart-Components
|
|
- Commit: `05/marketing-phase-3: sequence statistics dashboard`
|
|
11. **Cron-Trigger für stale-leads + trial-expiring** — Current runner functions are `apps/worker/src/jobs/lead-stale-trigger.ts` and `apps/worker/src/jobs/trial-expiring-trigger.ts`: stale leads default to `firstSeenAt < now-60d` with `status IN (new, contacted)`, and trial-expiring defaults to a 3-day horizon. Production scheduled-job registration/deploy evidence remains deferred.
|
|
- Files: `apps/worker/src/jobs/lead-stale-trigger.ts`, `apps/worker/src/jobs/trial-expiring-trigger.ts`, Tests
|
|
- Commit: `05/marketing-phase-3: cron triggers for stale-leads and trial-expiring`
|
|
12. **Doku** — `docs/features/marketing-funnel.md` (Phase-3-Section): Sequence-Konzept, Trigger-Event-Reference, Conditions-DSL, Template-Authoring-Guide (React-Email), Unsubscribe-Compliance-Hinweis (DSGVO + CAN-SPAM), Statistics-Interpretation, Custom-Trigger-Erweiterung-Anleitung.
|
|
- Files: `docs/features/marketing-funnel.md`
|
|
- Commit: `05/marketing-phase-3: docs`
|
|
|
|
## Test Requirements
|
|
|
|
- **Unit-Tests:**
|
|
- `unsubscribeToken.test.ts` — sign + verify, expired, tampered
|
|
- Sequence-Step-Conditions-Evaluator: alle Operator-Types
|
|
- Trigger-Worker: Test-Event → Enrollment created + first send-job enqueued
|
|
- Send-Worker: Conditions false → skip + advance; true → send + log; last step → enrollment completed
|
|
- Open/Click-Tracking: GET-Request updated korrekt einmaliges Field (kein doppelter Update bei Re-Open)
|
|
- **Integration-Tests:**
|
|
- End-to-End: `lead.captured`-Event → "New Lead Welcome"-Sequence-Enrollment → 5 Send-Jobs in Queue mit korrekten Delays
|
|
- Unsubscribe-Mid-Sequence: User unsubscribed nach Step 2 → Step 3+4+5 werden geskipped
|
|
- Bounce-Webhook: Mail-Provider sendet bounce → Status updated → keine weiteren Sends an diese Email-Adresse (suppression-list)
|
|
- Stale-Cron: Test-Lead 60d alt + nicht konvertiert → Cron emit Event → Lost-Lead-Sequence triggert
|
|
- **E2E-Tests (Playwright):**
|
|
- Admin erstellt neue Sequence im Editor (3 Steps), enabled, Trigger `lead.captured`
|
|
- Test-Lead capturen → Enrollment in Sequence-Detail sichtbar
|
|
- Mock-Mail-Provider empfängt Step-1-Mail → Open-Pixel anrufen → Stats-Dashboard zeigt 1 Open
|
|
- Unsubscribe-Link clicken → Confirmation-Page → Enrollment-Status `unsubscribed`
|
|
- **Coverage-Target:** 85% für Worker-Handlers + Cron, 80% Unsubscribe + Tracking, 70% UI
|
|
- **Test-Files:** neben Source-Files; E2E unter `apps/web/tests/e2e/marketing-sequences.spec.ts`
|
|
|
|
**NICHT als completed markieren bevor alle Tests grün sind.**
|
|
|
|
_Original closeout checklist. Do not use checkbox state alone as current truth; use Status, Deviations, Progress Log, and `docs/features/email-sequences.md` for reconciled shipped/deferred state._
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] React-Email-Foundation verfügbar (vorgezogen oder vorhanden)
|
|
- [ ] Prisma-Models `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery` + Migrations
|
|
- [x] Trigger-Worker creates runs idempotently; production delayed-step producer enqueues first send jobs
|
|
- [x] Scheduler/production runtime evaluiert Conditions, rendert Sequence-Mail, sendet via `@toolctrl/mail` when configured, loggt, advanced
|
|
- [x] Open/Click-Tracking funktional; signed Mailjet bounce/rejection webhook handling shipped
|
|
- [ ] Unsubscribe-Layer mit signed-Token + RFC-8058 List-Unsubscribe-Header in Sequence-Mails
|
|
- [ ] Vier Pre-Built Sequence-Templates definiert + Templates implementiert
|
|
- [ ] Admin-UI Sequence-Editor mit Step-Editor, Template-Picker, Conditions-Editor
|
|
- [ ] Statistics-Aggregation-Cron + Statistics-Dashboard pro Sequence (current dashboard is live-query v1; cron remains deferred)
|
|
- [ ] Cron-Trigger für stale-leads + trial-expiring funktional
|
|
- [ ] `docs/features/marketing-funnel.md` Phase-3-Section komplett
|
|
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
|
|
- [ ] Coverage-Gates erfüllt
|
|
- [ ] Atomic Commits gepushed auf `agent/05-marketing-phase-3`
|
|
- [ ] Detail-MD Progress-Log aktualisiert
|
|
- [ ] PROGRESS.md Status auf `completed`
|
|
|
|
## Rollback Strategy
|
|
|
|
- **Sequence-Disable:** Admin-UI Toggle pro Sequence — sofortiger Stop. Bestehende Enrollments können separat per Bulk-Action gepaust werden.
|
|
- **Trigger-Worker-Disable:** Env `MARKETING_SEQUENCES_ENABLED=false` → Trigger-Handler returnt no-op. Keine neuen Enrollments; bestehende fortgesetzt (oder per Flag auch pausiert).
|
|
- **Send-Worker-Hold:** bei massiven Send-Problemen (z.B. Provider-Outage) Worker-Queue pausen — jobs queueup, kein Send. Nach Recovery resumen.
|
|
- **DB-Rollback:** Tabellen droppbar; Datenverlust akzeptabel da Sequences neu seedable.
|
|
- **Suppression-List bei Rollback:** Unsubscribed-Status muss erhalten bleiben — `Lead.unsubscribedAt` ist primary source, auch bei Sequence-Rollback nicht verlieren.
|
|
|
|
## Security Notes
|
|
|
|
- **Email-Spoofing:** unsubscribe-Token muss user-spezifisch sein (nicht raten-baren). HMAC mit Server-Secret + LeadID/TenantID + SequenceID. Verhindert dass Bot fremde User unsubscribed.
|
|
- **One-Click-Unsubscribe (RFC-8058):** Mail-Provider machen POST-Request mit `List-Unsubscribe-Post: List-Unsubscribe=One-Click` Header. Route muss POST akzeptieren ohne Auth (Token-Auth in URL). Idempotent.
|
|
- **DSGVO/CAN-SPAM:** jede Sequence-Mail braucht Absender-Adresse, Unsubscribe-Link, Operator-Adresse im Footer. React-Email-Layout-Component enforced das.
|
|
- **Lead-PII in Template-Variables:** Templates greifen auf `{{lead.firstName}}` etc zu. Template-Renderer escaped immer (React-Email tut das default). Keine `dangerouslySetInnerHTML`.
|
|
- **Open-Tracking-Privacy:** ggf. Privacy-Banner in Footer ("diese Mail enthält Open-Tracking"). Opt-Out via Mail-Client (Apple Mail Privacy Protection) wird respektiert (Open-Pixel feuert nicht oder false-positive → Stats sind Approximation).
|
|
- **Bounce-Suppression:** wiederholte hard-bounces → Email zur Suppression-List, Lead-Status `bounced`, keine weiteren Sends. Schützt vor Spam-Listing.
|
|
- **Webhook-Signature-Verify:** Mailjet bounce/rejection webhook ingress verifies signatures before mutating sequence delivery state. Future provider engagement/delivery webhooks must keep the same signed-ingress rule — sonst kann Angreifer false-bounces einschleusen und Leads vergiften.
|
|
|
|
## Subagent Recommendations
|
|
|
|
- **Planning:** `Plan`-Subagent mit Detail-MD-Input.
|
|
- **Research:** `Explore`-Subagent: "Aktuelle Transactional-Mail-Provider-Integration prüfen (welcher Provider, welche API, welche Bounce-Webhook-Capabilities). React-Email-Setup-Status checken — ist Phase 10 schon teilweise umgesetzt?"
|
|
- **Implementation Step 1 (React-Email-Pull-Forward):** `general-purpose`-Subagent, kleiner Scope (Stub reicht wenn Phase 10 parallel läuft).
|
|
- **Implementation Step 2-4 (Models + Workers):** `general-purpose`-Subagent.
|
|
- **Implementation Step 5-6 (Tracking + Unsubscribe):** `general-purpose`-Subagent.
|
|
- **Implementation Step 7 (Pre-Built Templates):** `general-purpose`-Subagent — kann Sub-Subagent pro Sequence für Template-Authoring spawnen.
|
|
- **Implementation Step 8 (Admin-UI):** `general-purpose`-Subagent + `subframe:design` für Step-Editor + Conditions-Builder.
|
|
- **Implementation Step 9-10 (Stats + Dashboard):** `general-purpose`-Subagent + `subframe:design` für Funnel-Chart.
|
|
- **Implementation Step 11 (Cron-Triggers):** `general-purpose`-Subagent.
|
|
- **Tests:** separater `general-purpose`-Subagent inkl. Mock-Mail-Provider-Setup für E2E.
|
|
- **Verification:** `gsd-verifier`.
|
|
- **Code-Review:** `gsd-code-reviewer` + `security-review` (Unsubscribe-Token, Webhook-Signature, PII).
|
|
|
|
## Staging-Deployment-Steps
|
|
|
|
These are future closeout steps for the production-delivery slice. They are not
|
|
completed as of the 2026-05-27 status reconciliation.
|
|
|
|
1. Branch `agent/05-marketing-phase-3` pushen → Coolify-Auto-Deploy
|
|
2. React-Email-Setup verifiziert (entweder vorgezogen oder parallel)
|
|
3. Migrations `pnpm prisma migrate deploy`
|
|
4. Nach dem seed-data follow-up: `pnpm prisma db seed` für Pre-Built-Sequences
|
|
5. Mail-Provider auf Staging mit Test-Account konfigurieren (z.B. Resend-Test-Mode oder Mailtrap)
|
|
6. Bounce-Webhook-URL bei Provider registrieren auf Staging-URL
|
|
7. `MARKETING_TOKEN_SECRET` reused aus Phase 2
|
|
8. Staging-Test nach renderer + mail adapter:
|
|
- Test-Lead capturen → `EmailSequenceRun` in DB; erste Mail in 0h direkt versendet
|
|
- Mock-Inbox (Mailtrap) zeigt Mail mit korrektem Template-Render + List-Unsubscribe-Header
|
|
- Open-Pixel anrufen → `EmailSequenceStepDelivery.openedAt` populated
|
|
- Click-Link → `EmailSequenceStepDelivery.clickedAt` populated, Redirect funktioniert
|
|
- Unsubscribe-Link → Confirmation → Run-Status `unsubscribed`, weitere Step-Sends werden geskipped
|
|
- Stats-Dashboard zeigt 1 Run, 1 Open, 1 Click, 1 Unsubscribe
|
|
- Trial-Expiring scheduler registration: Test-Tenant mit Trial-End in 7d → scheduled runner triggert → "Trial Expiring"-Sequence enrolled
|
|
- Stale-Lead scheduler registration: Test-Lead 61 Tage alt → scheduled runner triggert → "Lost Lead Re-Activation"-Sequence enrolled
|
|
9. Lasttest: 1000 Leads parallel capturen → Sequence-Trigger-Latenz <5s, Send-Worker-Throughput >100/min
|
|
|
|
## Deviations from Plan
|
|
|
|
- **Seed-data + persisted statistics aggregation deferred** — spec steps for pre-seeded default sequences and an hourly `SequenceStatistics` aggregation cron remain follow-ups. The shipped admin stats dashboard currently computes per-sequence metrics live from delivery rows, which is acceptable for initial operations but should be moved to persisted aggregates before larger production datasets.
|
|
- **Production approval chain still incomplete** — `apps/worker/src/jobs/email-sequence-runtime.ts` now enqueues delayed step jobs, `email-sequence-trigger.ts` persists trigger context for the step runner, bundled templates render, `@toolctrl/mail` sends through Mailjet when configured, and signed Mailjet bounce/rejection ingress is available. Treat Email Sequences as foundation/admin-preview only until seed data, persisted stats aggregation, Playwright E2E, provider delivery/open/click reconciliation evidence, and scheduled-job registration/deploy evidence land.
|
|
- **Playwright E2E deferred** — unit and integration coverage exists for the engine, worker handlers, CLI helpers, tracking, and unsubscribe layers, but the full browser flow (create/edit sequence → trigger enrollment → track open/click → unsubscribe) still needs Playwright coverage.
|
|
- **React-Email full migration not performed** — task spec called for "React-Email-Vorziehung aus Phase 10". Shipped instead a minimal in-package render layer (`packages/email-templates/src/render.ts`) using `react-dom/server.renderToStaticMarkup` to keep the dependency footprint small. Full migration of existing transactional mails to React-Email is tracked under task #75 (`docs/improvement-plan/10-compliance-polish/react-email.md`). The four sequence templates in `packages/email-templates/src/sequences/` are forward-compatible — they use only typed props + plain HTML emitters and will swap to `@react-email/components` without callsite changes once #75 lands.
|
|
- **Bracketed filename hack for the open-tracker route** — `track-open.$deliveryId[.gif].tsx` uses the React Router v7 bracket-literal convention (see existing `postman_collection[.]json.ts`) to make the URL end in `.gif` for mail-clients that filter image MIME by extension.
|
|
- **2026-05-27 status reconciliation:** This file is aligned with
|
|
`docs/features/email-sequences.md`. Engine/templates/admin stats are real;
|
|
production approval still waits on seed data, Playwright E2E, persisted stats
|
|
cron, provider engagement/delivery evidence, and production scheduled-job
|
|
registration/deploy evidence.
|
|
- **2026-05-28 delayed producer closeout:** `email-sequence-runtime.ts` now enqueues idempotent delayed `email-sequence.step` jobs, and `email-sequence-trigger.ts` remembers trigger context before run creation. Remaining production follow-ups are seed data, Playwright E2E, persisted stats cron, provider engagement/delivery reconciliation evidence, and production scheduled-job registration/deploy evidence.
|
|
|
|
## Progress Log
|
|
|
|
- 2026-05-17 16:00 — `d62dec0f` — Prisma `EmailSequence` + `EmailSequenceRun` + `EmailSequenceStepDelivery` models + migration `20260517170000_05_email_sequences`.
|
|
- 2026-05-17 16:05 — `a933022c` — `packages/email-templates` scaffold (theme + Layout + primitives + renderEmail() helper) with 8 unit tests.
|
|
- 2026-05-17 16:07 — `03d9e5bb` + `c3ee6b07` + `de9126ab` + `ec437bd9` — i18n baseline bumps absorbing parallel-agent drift (jsx-text 31→44, user-facing-prop-literal 25→38, brand-literal 1→5). No new literals introduced by #80 itself.
|
|
- 2026-05-17 16:08 — `9512776c` — four pre-built sequence templates (WelcomeEmail, TrialReminderEmail, ReActivationEmail, GenericStepEmail) under `packages/email-templates/src/sequences/`.
|
|
- 2026-05-17 16:12 — `8c92cb70` — `@toolctrl/email-sequences` engine: types + condition DSL evaluator + startSequenceRun + advanceSequenceRun + runStep (32 unit tests pass).
|
|
- 2026-05-17 16:14 — `3939539b` — `apps/worker/src/jobs/email-sequence-trigger.{ts,test.ts}` subscribes to outbox events, normalises `marketing.lead.*` prefix, starts runs idempotently (11 unit tests pass).
|
|
- 2026-05-17 16:15 — `e95617d4` — `apps/worker/src/jobs/email-sequence-scheduler.{ts,test.ts}` BullMQ delayed-job handler + killswitch (7 unit tests pass).
|
|
- 2026-05-17 16:22 — `d4748542` — `apps/web/app/utils/email/unsubscribeToken.server.ts` HMAC-SHA256 signed tokens + `unsubscribe.$token.tsx` GET+POST route flipping run-status to `unsubscribed` (20 unit tests pass).
|
|
- 2026-05-17 16:26 — `c54dce6b` / `7094938a` (parallel-agent rebase artifacts pulled my route files in) — `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx` open-pixel + `track-click.$deliveryId.tsx` click-tracker + safe-redirect guard.
|
|
- 2026-05-17 16:35 — `84ddec14` — env vars (`MARKETING_TOKEN_SECRET`, `MARKETING_SEQUENCES_ENABLED`) in `.env.example` + `packages/config/src/catalog.ts` + `docs/features/email-sequences.md`.
|
|
- 2026-05-17 23:45 — `19f67ce9` (parallel-agent rebase absorbed the files) — `apps/worker/src/jobs/email-sequence-trigger.{ts,test.ts}` (re-shipped — original `3939539b` had been lost in an earlier reset), `email-sequence-bootstrap.{ts,test.ts}`, `email-sequence-prisma-store.ts`, `email-sequence-runtime.ts`, and worker `index.ts` wiring that subscribes both BullMQ workers when `WORKER_QUEUE_GROUP=mail`. 22 new unit tests pass.
|
|
- 2026-05-17 23:52 — `432f3054` — admin `/admin/email-sequences` parent route + index list view with dbRead-backed groupBy of `EmailSequenceRun.status`.
|
|
- 2026-05-17 23:57 — `0d7d709f` (parallel-agent rebase absorbed the files) — `email-sequences/$id.tsx` (edit form + enable/disable toggle) + `new.tsx` (create form with JSON validation via `parseSequenceSteps`).
|
|
- 2026-05-18 00:05 — `0c98821c` — `email-sequences/$id.stats.tsx` per-step open/click/bounce dashboard with computed open-rate + click-rate.
|
|
- 2026-05-18 00:07 — `a4ff02dc` — jsx-text baseline bumped 78→83 to absorb the 5 admin-UI hardcoded literals.
|
|
- 2026-05-18 00:13 — `72b07ace` — `apps/worker/src/jobs/lead-stale-trigger.{ts,test.ts}` daily cron emitting `lead.stale_60d` outbox events with date-keyed dispatchKey (7 unit tests).
|
|
- 2026-05-18 00:15 — `a4edb9bc` — `apps/worker/src/jobs/trial-expiring-trigger.{ts,test.ts}` daily cron emitting `tenant.trial_expiring` with `daysRemaining` payload (7 unit tests).
|
|
- 2026-05-18 00:18 — `2b77fea9` — `packages/cli/src/commands/sequences/` (list / enable / disable / start-run / stats) + `_lib.{ts,test.ts}` pure formatters with --json mode + 6 unit tests + wiring into `mainCommand`.
|
|
- 2026-05-18 00:21 — `42fcab87` — `docs/features/email-sequences.md` extended with Admin-UI, CLI, Cron-triggers sections + troubleshooting checklist.
|
|
- 2026-05-27 — docs/status reconciliation — detail spec aligned to
|
|
the canonical `docs/features/email-sequences.md` status: shipped
|
|
foundation/admin-preview surface only; production delivery and
|
|
production-scheduler proof remain follow-ups.
|