Marketing Module Technical Specifications

The Marketing module orchestrates the following capability domains:

• Campaigns — orchestration and Wilson Score A/B testing
• Automation — visual journey execution
• Newsletters — subscription management, CSV import
• Email providers — multi-provider send abstraction with automatic failover
• Deliverability — webhook ingestion, bounce/complaint handling
• Dispatch queue — high-throughput batch delivery
• GDPR — SHA-256 anonymization, consent management
• AI visibility — AI-powered subject line optimization
• SMS — AWS SNS / Twilio dispatch
• Domain authentication — SPF/DKIM/DMARC pre-flight checks
• Suppression — global suppression list management
• RFM scoring — Recency/Frequency/Monetary segmentation
• Double opt-in — confirmation flow, token management
• Unsubscribe — RFC 8058 one-click handling
• Dynamic content — per-subscriber personalization

Campaign dispatch is queue-backed, ensuring reliable delivery even during server restarts.

Campaigns move through a straightforward lifecycle: draft, resolve recipients from a segment, pre-process content (merge variables, inject tracking, select a variant), queue the send, and track results as they come in.

Campaign send flow:

1. Validate — campaign exists, status is not already "completed" or "sending"
2. Guard against double-sends — a duplicate launch (double-click or retry) can't re-enqueue the entire subscriber list
3. Set status to "sending" — before queueing jobs
4. Resolve recipients from the target segment
5. Pre-process content — template variables replaced, tracking tokens injected, variant selected
6. Create send records — one per recipient, created upfront so results can be tracked as they arrive
7. Batch and dispatch — recipients are chunked into isolated batches so one bad batch never affects the rest of the send

Wilson Score A/B testing: Rather than comparing raw open-rate percentages, each variant's true performance is estimated as a 95%-confidence lower bound. A variant only wins when its lower bound clearly beats the alternative's — not just when its raw rate happens to be higher.

Auto-selection criteria: A winner is only auto-selected once the leading variant's confidence interval clearly beats the runner-up's, with a meaningful lead — never from a raw percentage difference alone. This prevents auto-selecting a result that isn't statistically meaningful.

Design philosophy: Campaigns are split into batches. Each batch is dispatched as an independent unit of work — failures are isolated per batch, not per campaign, so one bad batch never takes down an entire send.

Workers are stateless: Content is fully pre-processed before queueing — subject lines, HTML, and tracking tokens are all resolved ahead of time. Workers receive a ready-to-send recipient list; there's no additional database lookup at send time, which keeps dispatch fast and predictable.

Rate limiting: Configurable messages-per-second limit, tuned per deployment.

Retry: Multiple attempts with exponential backoff. Persistently failing sends are captured for manual review and retry rather than silently dropped.

Tracking tokens: Each send gets a unique, unguessable tracking token used to match open/click webhook events back to the specific recipient.

Visual builder, real execution: The journey builder isn't just a diagram — every node you place on the canvas maps to a persisted, resumable step that's evaluated against live subscriber events.

Enrollment lifecycle:

• Enroll — validates the automation is active, checks for an existing enrollment (respecting re-enrollment settings), creates the enrollment, and processes the first step
• Process — executes the current step and advances; a recursion guard protects against infinite loops from misconfigured condition nodes
• Resume — when a wait/delay step's timer fires, execution resumes automatically from the saved position
• Exit — marks the enrollment exited and logs the reason to history

Reliability: Automations run with configurable concurrency. Failed steps are captured and surfaced for manual inspection and retry rather than silently dropped — a transient failure never quietly loses a subscriber's place in a journey.

Step types executed:

• Email step — render template, send, log analytics
• SMS step — compose, send, track delivery
• Wait step — schedule a delayed resume, set enrollment status to "waiting"
• Condition step — evaluate a boolean, branch to true/false path
• Goal step — set enrollment status to "completed"
• Webhook step — fire HTTP POST to an external endpoint
• Exit step — mark enrollment exited

Subscribe flow:

1. Find or create the subscriber
2. Check for an existing subscription to this newsletter
3. If already subscribed and active, no duplicate subscription is created
4. If double opt-in is required, generate a 72-hour confirmation token and set status to "pending"
5. Otherwise, create the subscription as active

CSV import with consent: Bulk imports parse a CSV (first row as headers), record the required consent text for each subscriber, and set status to "pending" (double opt-in) or "active" (admin import with confirmation skipped). Exports use the same format.

Key behaviors:

• Confirmation tokens are unique, unguessable, and expire after 72 hours
• Expired tokens are rejected at confirmation time — stale confirmations require re-subscribing
• Re-subscribing a previously unsubscribed contact resets their status to "pending"

Multi-provider architecture: Configure SendGrid, Mailgun, Resend, Postmark, SMTP, or Console (dev). The active provider is set per-tenant. Switching providers requires no code change — just a settings update.

Send flow:

1. Suppression check — never blocks on a database error (fail-open); on failure the check is logged and the send proceeds
2. Load the active provider configured for the tenant
3. Dispatch via the provider-specific adapter

Provider test flow: Send a diagnostic email to the configured sender address, measure latency, and persist the result (success, latency, error) for visibility in the admin UI.

Batch send: Iterates all recipients, collects results, and never aborts the whole batch on a single failure — each failure is logged individually.

RFC 8058 List-Unsubscribe-OneClick: Every send includes headers that Gmail, Yahoo, and Outlook honor for one-click unsubscribe — no landing page visit required.

Automatic selector detection: Common DKIM selector patterns used by major providers are probed automatically, so you don't need to know your provider's exact selector name in advance.

Scoring: SPF, DKIM, and DMARC are each checked; a stricter DMARC policy (reject, then quarantine, then monitor-only) earns a higher score, as does a passing SPF record and a validating DKIM selector.

Grades:

• A — SPF + DKIM + DMARC pass → proceed immediately
• B — SPF + DKIM pass, DMARC none → proceed with warning
• C — SPF or DKIM failing → block + alert admin
• F — Domain not configured → block + prevent send

Fast repeat checks: Results are cached briefly so rapid campaign launches aren't slowed down by redundant DNS lookups.