# Marketing-Funnel Overview This page is the canonical overview for the shipped lead-capture and self-service conversion foundation. Email sequences are covered separately in `docs/features/email-sequences.md`. This page also keeps the marketing-outbound boundary explicit: the `packages/marketing-outbound` adapters and `apps/worker/src/jobs/marketing-outbound.ts` handler are a shipped general handler foundation, but the general subscriber is not bootstrapped from `apps/worker/src/index.ts`. That foundation is separate from the `email-marketing` CRM-contact campaign plugin candidate in `docs/feature-decisions/email-marketing-decision-report.md`. The marketing-funnel ships a four-layer pipeline that lets external landing pages, ads, and blog CTAs feed structured leads into the operator-side admin inbox without an external CRM. | Layer | Component | |------------------|------------------------------------------------------------| | 1. Data model | `Lead` + `LeadEvent` Prisma tables (`prisma/schema/marketingLeads.prisma`) | | 2. Ingestion API | `POST /api/leads/capture` (`apps/web/app/routes/api.leads.capture.tsx`) | | 3. SDK | `apps/web/public/embed/marketing.js` (origin-served mini-snippet; CDN-ready while A7/B2 remains backlog) | | 4. Admin UI | `/admin/marketing-leads` (list) + `/admin/marketing-leads/:id` (detail) | ## Status machine Leads move through seven states: ``` new → contacted → qualified → trial → customer ↘ churned ↘ disqualified ``` Transitions are recorded as `LeadEvent` rows of type `status-changed` for the activity-timeline in the detail-view. Operators move leads forward (or to a terminal state) from the detail page. The `score`, `notes`, and `convertedAt` columns are operator-managed. ## Attribution Every Lead carries first-touch attribution columns populated by the SDK on the initial visit and persisted in localStorage so subsequent page visits attribute to the same source: | Column | Source | |---------------|-----------------------------------------------------| | `utmSource` | `?utm_source=…` | | `utmMedium` | `?utm_medium=…` | | `utmCampaign` | `?utm_campaign=…` | | `utmTerm` | `?utm_term=…` | | `utmContent` | `?utm_content=…` | | `gclid` | `?gclid=…` (Google Ads click identifier) | | `fbclid` | `?fbclid=…` (Meta Ads click identifier) | | `referrer` | `document.referrer` | | `landingPage` | `location.href` at the first visit | | `firstSeenAt` | `new Date()` on initial insert (never overwritten) | | `lastTouchAt` | `new Date()` on every re-capture | `source` is operator-supplied (via the form's `data-source` attribute or the SDK call's `source` field) and identifies the surface — `"landing-pro"`, `"blog-cta"`, `"webinar-form"` — distinct from the paid-channel `utmSource`. ## Anti-spam (defence in depth) The capture endpoint stacks four layers, each weakening different bot classes; none of them is sufficient alone. 1. **Origin allowlist** — `MARKETING_ALLOWED_ORIGINS` (CSV with `*.host` wildcards). 403 on miss. Defeats browser-based form-spam from non-whitelisted pages; can be spoofed by server-to-server bots. 2. **Honeypot** — the SDK injects a hidden `website_url` field. When the server sees it filled, it responds with a silent 204 and inserts nothing. 80%+ of crude form-fillers fall here. 3. **Sliding-window rate-limit** — 5/min per IP (configurable via `MARKETING_RATE_LIMIT_PER_MIN`) and 1/min per email. The per-email limit doubles as a re-capture dedupe so the LeadEvent timeline doesn't flood. 4. **Cloudflare Turnstile** (optional) — gated behind the `marketing-funnel-turnstile` feature flag. When enabled, callers must include a valid `turnstileToken`; verification hits the Cloudflare API. Successful responses are intentionally identical for new and duplicate emails (empty body, 200 OK) so bots cannot enumerate the customer list. ## API contract ### `POST /api/leads/capture` Public, CORS-enabled. Accepts `application/json` or `application/x-www-form-urlencoded`. Body: ```json { "email": "alice@example.com", "firstName": "Alice", "lastName": "Liddell", "phone": "+44 …", "company": "Acme", "source": "landing-pro", "attribution": { "utmSource": "google", "utmCampaign": "spring-launch", "gclid": "EAIaIQ…", "referrer": "https://google.com/", "landingPage": "https://example.com/landing" }, "turnstileToken": "0.OOOO…", "website_url": "" } ``` Responses: | Status | Meaning | |--------|--------------------------------------------------| | 200 | Captured (or silently de-duplicated). Empty body.| | 204 | Honeypot triggered or per-email rate-limit hit. | | 400 | Invalid payload shape. | | 403 | Origin not allowlisted or Turnstile failed. | | 413 | Body exceeds 32 KiB. | | 429 | Per-IP rate-limit exceeded. | ### `OPTIONS /api/leads/capture` CORS preflight. Echoes the matched origin in `Access-Control-Allow-Origin`. ## SDK (`marketing.js`) Drop the script tag onto every marketing page: ```html ``` The script self-bootstraps on `DOMContentLoaded`: - Reads `?utm_source/medium/campaign/term/content`, `?gclid`, `?fbclid` from the URL and merges them with the stored first-touch attribution. - Persists merged attribution to `localStorage["__tcm_attr"]` so multi-page flows hit the same lead source. - Auto-binds any `