Marketing Features

1

2

3

4

1Segments — build targeted audience groups with filters

2Campaigns — create and manage outreach campaigns

3Email Campaigns — send templated emails to segments

4Promo Codes — generate discount codes for campaigns

The Marketing module is the platform's growth engine. It lets you describe an audience once (a Segment), then reuse that audience to send email campaigns, invite people to outreach campaigns, and distribute discount codes — while a separate, always-on layer of conversion surfaces quietly converts anonymous Reader Portal visitors into subscribers. Everything is admin-authored, persisted in PostgreSQL, and delivered through your configured email provider or rendered on the public Reader Portal.

1. Executive Overview

What It Does

The Marketing Features module provides a comprehensive marketing, outreach, and audience engagement system for the Hyphen Publishing Platform. It enables publication administrators to:

• Build and manage audience contact lists from CSV imports, campaign submissions, and newsletter signups
• Create targeted user segments with advanced filtering across both registered readers and external audience contacts
• Launch outreach campaigns with customizable landing pages, dynamic forms, event content, incentives, and social integration
• Send email campaigns to segmented audiences using templated emails with engagement tracking
• Manage newsletter editions authored in Strapi CMS, sent as email campaigns, and archived for readers
• Create and distribute promotional codes with configurable discount types and validity rules
• Deploy conversion surfaces (modals, banners, slide-ins) with targeting rules and trigger-based activation on the Reader Portal
• Track engagement analytics across campaigns, email deliveries, and conversion surfaces with integrated GA4 and internal metrics

Who Uses It

Business Problem It Solves

Publications need to grow their readership, retain subscribers, and promote events/content. This module provides a unified platform to:

• Acquire new readers through outreach campaigns (student programs, events, lead generation)
• Convert anonymous visitors to subscribers through strategically-placed conversion surfaces
• Engage existing audiences through segmented email campaigns and newsletters
• Track marketing ROI through integrated analytics across all channels

2. Feature Scope

In Scope

Out of Scope

• A/B testing for conversion surfaces (planned for future)
• Geographic targeting for conversion surfaces (planned)
• Webhook events for campaign lifecycle (planned)
• Content-aware inline embed positioning (planned)
• Admin preview mode for conversion surfaces (planned)

Related Modules / Dependencies

3. Roles & Permissions

Marketing Permissions

Inbox access is per-panel. The Inbox nav entry appears if a user holds any of the three READ permissions. Inside the hub, each panel is gated independently — a user with only MARKETING_FEEDBACK_SUBMISSIONS_READ sees the Feedback panel and an "Access Restricted" message on the others. The three READ/UPDATE pairs are granted to the editor, sales_manager, and marketing_manager roles by default.

Additional Related Permissions

RBAC Configuration

Permissions are assigned to roles in Admin Console → Settings → Roles & Permissions. Each role can be granted specific marketing permissions. The Marketing Hub page itself controls card visibility based on permissions — users without MARKETING_CAMPAIGNS_READ will not see the Campaigns card.

4. Architecture & Design Overview

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        ADMIN CONSOLE                            │
│  ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌─────────────┐ │
│  │ Marketing│ │  Email       │ │  Segments  │ │  Conversion │ │
│  │ Hub      │ │  Campaigns   │ │  Builder   │ │  Surfaces   │ │
│  └────┬─────┘ └──────┬───────┘ └─────┬──────┘ └──────┬──────┘ │
│       │              │               │               │         │
│  ┌────┴──────────────┴───────────────┴───────────────┴──────┐  │
│  │              /api/marketing/*  (REST APIs)               │  │
│  └────┬──────────────┬───────────────┬───────────────┬──────┘  │
│       │              │               │               │         │
│  ┌────┴──────────────┴───────────────┴───────────────┴──────┐  │
│  │                  Prisma ORM (PostgreSQL)                  │  │
│  │  OutreachCampaign | EmailCampaign | UserSegment |        │  │
│  │  AudienceContact | ConversionSurface | etc.              │  │
│  └──────────────────────────────────────────────────────────┘  │
│       │                                                        │
│  ┌────┴────┐  ┌───────────┐  ┌──────────────┐                │
│  │ Strapi  │  │ SendGrid/ │  │  S3 Storage  │                │
│  │  CMS    │  │  SMTP     │  │  (uploads)   │                │
│  └─────────┘  └───────────┘  └──────────────┘                │
└─────────────────────────────────────────────────────────────────┘
         │                         │
         ▼                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                       READER PORTAL                             │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │  Campaign    │  │  Newsletter  │  │  Conversion Surface   │ │
│  │  Landing     │  │  Archive     │  │  Renderer (global)    │ │
│  │  Pages       │  │  Pages       │  │  Modals/Banners/etc.  │ │
│  └──────────────┘  └──────────────┘  └───────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Key Entities & Models

Workflow / State Models

Outreach Campaign Status Flow:

draft ──publish──→ active ──unpublish──→ paused ──publish──→ active
                     │                      │
                  complete               archive
                     │                      │
                     ▼                      ▼
                 completed ──archive──→ archived

Email Campaign Status Flow:

draft ──schedule──→ scheduled ──cron trigger──→ sending ──→ sent
  │                                                  │
  └──send now──→ sending ──────────────────────→ sent/failed

Campaign Submission Status Flow:

pending_review ──approve──→ approved
       │                        │
       ├──reject───→ rejected   └──generate promo──→ (with PromotionalCode)
       │
       └──request info──→ needs_info ──resubmit──→ pending_review

Conversion Surface Status Flow:

draft ──activate──→ active ──pause──→ paused ──activate──→ active
  │                   │                  │
  └──schedule──→ scheduled             archive
                  │                      │
                  └──cron──→ active      ▼
                      │              archived
                   expires
                      │
                      ▼
                   expired

How It Works (Behind the Scenes)

Every marketing feature follows the same end-to-end shape: an admin authors something in the Admin Console UI, the browser calls a REST endpoint under /api/marketing/*, the handler enforces RBAC and writes to PostgreSQL via Prisma, and the result is then either delivered as email or rendered on the Reader Portal. Newsletters add one extra hop — content is authored in Strapi and bridged into a Prisma EmailCampaign at send time.

Reading the diagram:

1. Authoring happens entirely in the Admin Console. No marketing object is created directly in the database.
2. Recipient resolution is centralized in resolveSegmentRecipients() — both the manual Send action and the scheduled-email cron call it, so a segment that mixes registered readers and audience contacts always resolves identically (deduped by email, opt-in enforced, unsubscribed/banned/anonymised addresses excluded).
3. Delivery feedback (opens, clicks, bounces, unsubscribes) returns from the provider via webhook and is written back onto the campaign/invitation record — the same row that triggered the send.
4. Reader-facing surfaces (campaign landing pages, the newsletter archive, conversion overlays) read published data from the database; the Reader Portal never writes marketing config, only events (submissions, conversion interactions).

Concepts: Segments, Campaigns & Coupons

Four concepts underpin the whole module. Understanding how each is evaluated — not just configured — is the key to predictable campaigns.

Audience segmentation — how segments are evaluated & previewed

A Segment (user_segments table) is not a saved list of people. It is a saved set of filter rules stored as a JSON filters object. Members are resolved dynamically at query time every time you preview, count, send, or export — so a segment automatically grows or shrinks as readers and contacts change.

• Two source tables, one result. Depending on the Contact Source filter, a segment queries the Reader table, the AudienceContact table, or both, then de-duplicates by email (case-insensitive).
• Filter logic. Rules are combined with AND between filter groups and OR within a group. Example: (Subscription = Active OR Trial) AND (Tag = "students").
• Base guards always apply. Reader resolution unconditionally starts from { isActive: true, isBanned: false } — GDPR-anonymised and banned readers are never returned, even before your filters run. Audience contacts must have isActive: true.
• Live preview. As you edit filters, the right sidebar fires a debounced count (POST /api/marketing/segments/preview) so you see the audience size before saving. Preview Members returns a sample (up to ~20) labelled by source. The stored memberCount + lastCountedAt cache the most recent count for fast list display.

Campaign types & lifecycle

There are two distinct things called "campaign" — keep them separate:

• Outreach campaign lifecycle is a strict state machine driven by the Publish endpoint (publishing validates name, slug, dates, and at least one form field). The landing page renders differently per status and, for event-type campaigns, per timing (Upcoming / Happening Now / Recap). See Sections 8–9.
• Email campaign lifecycle adds an honest intermediate accepted state: the provider returned 2xx but inbox delivery isn't yet confirmed; the row only flips to sent ("Delivered" in the UI) once the delivery webhook confirms arrival. The delivered counter is an evolving number that keeps rising for ~22 minutes post-send as transient failures are retried.
• Campaign types (CampaignType table) are admin-managed categories. The type is a free-form slug — admins can create custom types (e.g. "Festival Campaign") and optionally pin them to a reader-portal template via templateMappingHint.

Promo codes & coupons

Discounts come from two models with different lifecycles:

Both are checked by the public validate/redeem endpoints. Validation (POST /api/promo/validate, 20 req/min/IP) confirms the code exists, is active, not expired, and under its usage limit. Redemption (POST /api/promo/redeem, 5 req/15 min/IP) atomically claims a slot; for trial_days codes it also creates the reader account + subscription in one transaction.

Forms & submissions

Outreach campaigns carry an admin-built form (the formFields JSON). When a visitor submits on the landing page, the platform creates a CampaignSubmission, upserts an AudienceContact from the form data (so the lead re-enters your segment pool), and routes the row into the approval workflow (pending_review → approved / rejected / needs_info). Approving a submission can auto-generate a promo code and trigger an email. See Sections 8 and 10.

Configuration Reference

Field-by-field reference for the main marketing objects. Where configured is the Admin Console UI path unless it says env (backend environment variable). Roles refer to the permission keys in Section 3.

Segment rules (user_segments)

Segments do not expose account-status filtering: every segment targets only active, non-banned readers by design.

Outreach campaign fields (outreach_campaigns)

Email campaign fields (email_campaigns)

Coupon fields (discount_coupons)

Campaign form fields (formFields entries) & QR

Key backend / environment settings

Dependencies & Impact

Marketing is highly interconnected — most features fail silently or partially if an upstream dependency is missing, so review this before going live.

Impact when a dependency is broken:

• No email provider → email campaigns hang in sending, invitations and approval/rejection emails never arrive.
• Cron not running → scheduled emails, scheduled invitations, and campaign auto-completion never fire.
• Strapi down → newsletter editions cannot be authored or published (other features unaffected).
• S3 unconfigured → campaign forms with photo/file fields reject uploads.
• RBAC misconfigured → the relevant Marketing Hub cards and actions are hidden for the role.

5. Prerequisites & Setup Requirements

Critical Prerequisites (Must be configured before marketing features work)

1. Email Provider Configuration

Marketing relies heavily on email delivery. Without a configured email provider, email campaigns, invitations, and submission notifications will fail.

Verify: Admin Console → Settings → Email → Accounts → click an account → Verify connection. A successful probe returns latency in ms; a failure returns the provider's actual error message. Also confirm at Settings → Email → Purposes that marketing_campaign and newsletter have a primary account. See the Email System Guide.

2. Email Templates

Campaign-related emails (approval, rejection, invitation, notification) require email templates to be seeded.

Action: Seed default templates by calling POST /api/marketing/email-templates/seed or creating them manually in Admin Console → Settings → Email → Templates. Each template should also carry a defaultPurposeKey (set on the editor's Email purpose dropdown) so the right account ships it.

Required template keys:

• campaign_submission_approved
• campaign_submission_rejected
• campaign_invitation
• campaign_notify_new_campaign

3. Email Preferences & Branding

Configure email branding (logo, colors, publication name, footer, unsubscribe link) in Admin Console → Settings → Email → Templates → Preferences to ensure all outgoing emails look professional and comply with CAN-SPAM requirements.

4. Strapi CMS Configuration (for Newsletters only)

Newsletter editions are authored in Strapi. Required settings:

Newsletter editions content type must exist in Strapi with fields: title, slug, previewText, content, plainTextContent, editionNumber, topic, publishDate, coverImage, status, isFeatured, priority.

5. S3 Storage Configuration (for file uploads)

Campaign form submissions may include file uploads (selfies, ID cards, documents).

6. Cron Job Configuration

Automated tasks require the cron system to be running.

All cron endpoints require: Authorization: Bearer <CRON_SECRET>

7. Webhook Configuration (for email engagement tracking)

To track email opens, clicks, bounces, and unsubscribes:

SendGrid:

• Register webhook URL: {ADMIN_CONSOLE_URL}/api/webhooks/sendgrid
• In SendGrid Dashboard → Settings → Mail Settings → Event Webhook
• Optional: Set SENDGRID_WEBHOOK_VERIFICATION_KEY for signature verification

Mailchimp/Mandrill:

• Register webhook URL: {ADMIN_CONSOLE_URL}/api/webhooks/mailchimp
• In Mandrill Dashboard → Settings → Webhooks
• Optional: Set MAILCHIMP_WEBHOOK_KEY for HMAC-SHA1 verification

8. Reader Portal URL Configuration

Campaign landing pages render on the Reader Portal. The Admin Console needs to know the Reader Portal URL for preview links and public campaign URLs.

9. RBAC Permission Assignment

Ensure the appropriate roles have marketing permissions assigned. Navigate to Admin Console → Settings → Roles & Permissions and grant the marketing permission group to roles that need access.

10. GA4 Configuration (for conversion surface analytics)

Conversion surfaces fire custom GA4 events. If you use Google Analytics:

GA4 events tracked: conversion_surface_impression, conversion_surface_click, conversion_surface_dismiss, conversion_surface_conversion, coupon_copied, newsletter_signup, registration_start.

5A. Sub-Module: Marketing Inbox (Triage Hub)

The Marketing Inbox consolidates three reader-originated message streams behind one nav entry: Campus Inquiries, Contact Submissions, and Feedback Submissions. Inbox is the single entry point for these streams.

Purpose

Give the marketing/editorial team one place to read and triage everything readers send in (as opposed to campaigns the team sends out): campus-visit requests, Contact-Us messages, and portal feedback.

Access

Admin Console → Marketing → Inbox

The page is a two-panel hub (same pattern as the Content Hub): a left sidebar lists the available streams and the right pane renders the selected panel. The active stream is held in the URL as ?type= (campus-inquiries, contact-submissions, or feedback-submissions), so a panel is shareable/bookmarkable. The default stream is Campus Inquiries.

The Three Streams

Each panel has status tabs with live counts, a table view, and a detail modal. Opening a new item auto-marks it read (requires the stream's _UPDATE permission). The detail modal lets you change status, record internal notes, and (feedback) assign the item to a team member.

Feedback Submissions (detail)

• The public form persists straight to a dedicated FeedbackSubmission table — anonymous submissions (no name/email) are accepted, and the route is rate-limited to 20 submissions per hour per IP. Nothing is routed through the email service, so feedback is never lost to a delivery failure.
• Each row carries: optional name/email, a 1–5 star rating, a category (general, bug, suggestion, content, other), the message, and the pageUrl the reader was on when they submitted.
• Triage actions (PATCH /api/marketing/feedback-submissions/[id]) are audit-logged (feedback_submission.update).

Business Rules

• The Inbox nav link is visible if the user holds any of the three READ permissions; individual panels are gated by their own READ permission.
• Status changes, notes, and assignment require the matching _UPDATE permission.
• No campaign, segment, or email-provider configuration is required for the Inbox to work — these streams are independent of the outbound stack.

6. Sub-Module: Audience Contacts

Purpose

Manage external audience contacts (people not yet registered as readers) for use in segments, campaign invitations, and email campaigns.

Access

Admin Console → Marketing → Segments → Contacts tab (Also accessible via Marketing → Audience, which redirects to the Contacts tab)

Key Features

6.1 View Contacts

• Table view with columns: Name, Email, Phone, Institution, Tags, Source, Created
• Search by name or email
• Filter by tags
• Sort by any column
• Pagination

6.2 Add Single Contact

1. Click "Add Contact" button
2. Fill in fields: Email (required), Name, Phone, Institution, Designation, City, State, Country, Tags
3. Click Save
4. Contact is created with source: 'manual'

6.3 Bulk Import via CSV

1. Click "Upload CSV" button
2. Drag-and-drop or browse to select a CSV file
3. Column Mapping Step: The system auto-detects columns. Map CSV columns to contact fields (email, name, phone, institution, etc.)
4. Preview Step: Review first 5 rows of mapped data
5. Click Upload
6. System upserts contacts by email (creates new, updates existing)
7. Results summary shows: created, updated, skipped, errors

CSV Requirements:

• Must have an email column (required)
• All other columns are optional
• Duplicate emails are updated (not duplicated)
• Tags can be specified as comma-separated values

6.4 Edit Contact

• Click any contact row to open the Edit Contact modal
• Modify fields and click Save

6.5 Delete Contact

• Select one or more contacts → click Delete in bulk actions
• Or click delete icon on individual row
• Soft delete by default (isActive = false)
• Hard delete available with ?hard=true query parameter (API only)

6.6 Export Contacts

• Click Export to download all active contacts as CSV

6.7 Auto-Created Contacts

Contacts are automatically created (upserted) from:

• Campaign form submissions: Tagged campaign_submission, with source detail of campaign name
• Newsletter signups: Tagged newsletter_signup

These auto-created contacts appear in the Contacts tab and can be included in segments.

Business Rules

• Email must be unique across all contacts
• Contacts with isActive = false are excluded from segments and email sends
• Unsubscribed contacts (unsubscribedAt set) are excluded from non-forced email sends
• A contact can be linked to a Reader record via readerId (one-to-one)

7. Sub-Module: User Segments

Purpose

Create targeted audience groups by combining filter criteria across both registered readers and audience contacts. Segments are used for email campaigns and campaign invitations.

Access

Admin Console → Marketing → Segments → Segments tab

Key Features

7.1 View Segments

• List view with columns: Name, Member Count, Filters (summarized), Created By, Last Counted
• Search by segment name
• Click any segment to view/edit

7.2 Create Segment

1. Click "New Segment"
2. Enter segment Name and optional Description
3. Build Filters using the sidebar filter groups:

4. Filters use AND logic between groups and OR logic within a group
5. The right sidebar shows a live member count (debounced, updates as you change filters)
6. Click "Preview Members" to see a sample of matching members
7. Click Save Segment

7.3 Edit Segment

• Open segment → modify filters → member count updates in real-time → Save

7.4 Preview Members

• Click "Preview Members" or open the segment → see paginated list of matching members
• Shows both readers and audience contacts with source labels
• Can exclude specific members from the segment preview

7.5 Export Segment

• "Export" downloads segment members as CSV
• Includes both readers and audience contacts with a source column

7.6 Delete Segment

• Only allowed if the segment is not used by active campaigns or invitations
• Attempting to delete a segment in use shows an error message

Business Rules

• Segment member count is auto-calculated when filters change
• Segments resolve members dynamically at query time (not static lists)
• When Contact Source includes "Audience Contacts" or "All", the segment queries both Reader and AudienceContact tables
• The lastCountedAt timestamp tracks when the member count was last refreshed
• Segment filter criteria are stored as a JSON object on the UserSegment model

8. Sub-Module: Outreach Campaigns

Purpose

Create multi-purpose outreach campaigns with customizable landing pages, dynamic forms, incentives, event content, and post-event materials.

Access

Admin Console → Marketing → Campaigns

Campaign Types

Additionally, admins can create custom campaign types via the Campaign Types management page.

8.1 Create Campaign (7-Step Wizard)

Navigate to Marketing → Campaigns → New Campaign

Step 1: Basics

• Campaign Name (required)
• URL Slug (required, unique, auto-generated from name)
• Campaign Type (select from admin-managed types)
• Description
• Start Date (required)
• End Date (required)

Step 2: Form Fields Build the campaign registration form using the form field builder:

• Add fields with types: text, email, phone, url, number, date, textarea, select, radio, checkbox, photo_selfie, photo_id_card, file_upload, institution_picker
• Configure per field: label, placeholder, required, help text, validation rules (minLength, maxLength, min, max, pattern), options (for select/radio/checkbox)
• Reorder fields via drag-and-drop
• Also configure Notify Form fields (shown on expired campaigns)

Step 3: Landing Page

• Landing Page Title
• Landing Page Subtitle
• Landing Page Content (rich text / HTML)
• Hero Image (via Media Picker)
• Success Title & Message (shown after form submission)
• Expired Title & Message (shown when campaign is past end date)
• Testimonials (add multiple: name, role, location, quote, rating, avatar via Media Picker)

Step 4: Event Details (for event-type campaigns)

• Speakers: Name, Role, Bio, Talk Title, Photo (Media Picker), Social Links (Twitter, LinkedIn, Website)
• Schedule: Multi-day agenda with sessions (time, title, description, speaker dropdown, location, type: keynote/panel/workshop/break/networking)
• Partners: Name, Logo (Media Picker), Tier (title_sponsor/partner/supporter/media_partner), Website
• Why Attend: Benefits list (title, description, icon)
• Venue Info: Name, Address, City, Map URL, Directions
• Live Stream: URL, Type (YouTube/Vimeo/Custom)

Step 5: Post-Event Content (for completed events)

• Gallery: Multiple images via Media Picker with captions
• Winners: Display mode (ranked/flat/categorized), Winner entries (name, award, category, rank, description, photo)
• Recording URL: Link to event recording
• Resources: Downloadable files (title, URL, type, description, thumbnail)

Step 6: Incentive

• Incentive Type: none, free_trial, percentage_discount, fixed_discount
• Incentive Value (e.g., 30 days trial, 20% off)
• Incentive Description
• Promo Code Prefix (for auto-generated codes)
• Promo Validity Days
• Linked Subscription Plan

Step 7: Review

• Comprehensive preview of all configured sections
• Click Create Campaign to save as draft

8.2 Edit Campaign

Navigate to Marketing → Campaigns → [Campaign Name] → Edit

All fields from the creation wizard are editable. Changes are saved immediately on form submission.

Important: Status changes are NOT allowed through the edit form. Use the Publish/Unpublish actions on the campaign detail page.

8.3 Campaign Detail Page (7 Tabs)

Navigate to Marketing → Campaigns → [Campaign Name]

8.4 Layout & Style Tab

The Layout & Style tab integrates with the platform's page template system:

• Select Template: Choose from available campaign-compatible templates
• Configure Sections: Customize the order and content of campaign page sections
• Save Draft: Save template changes without publishing
• Publish: Push template changes live to the reader portal
• Preview: Opens the reader portal campaign page in a new tab for visual review

Note: The preview requires the Reader Portal to be running. If preview shows "Preview Unavailable", verify NEXT_PUBLIC_READER_URL is correctly configured and the Reader Portal is running.

8.5 QR Code Tab

Generates a QR code linking to {READER_URL}/campaigns/{slug}. Can be downloaded for use in physical marketing materials.

8.6 Statistics Tab

Shows real-time campaign metrics:

• Total Submissions
• Pending Review Count
• Approved Count
• Rejected Count
• Conversion Count (submissions that resulted in subscriptions)
• Counts are sourced from actual submission records (not denormalized counters)

9. Sub-Module: Campaign Publishing & Landing Pages

Purpose

Control campaign visibility and manage the lifecycle of campaign landing pages accessible to the public.

Publishing Workflow

Publish a Campaign

1. Navigate to the campaign detail page
2. Ensure the campaign is in Draft or Paused status
3. Click "Publish"
4. System validates campaign completeness:
   • Name is set
   • Slug is set
   • Start date and end date are set
   • At least one form field is configured
5. If validation passes: status changes to Active
6. The campaign landing page is now live at {READER_URL}/campaigns/{slug}

Unpublish a Campaign

1. From an Active campaign, click "Unpublish"
2. Status changes to Paused
3. The landing page shows a "Campaign Paused" message to visitors

Complete a Campaign

1. From an Active campaign, click "Complete"
2. Status changes to Completed
3. The landing page shows an "Event Recap" or expired state with notify form

Archive a Campaign

1. From a Completed or Paused campaign, click "Archive"
2. Status changes to Archived
3. Campaign is hidden from public access

Landing Page URL

Every campaign has a public URL: {READER_URL}/campaigns/{slug}

This URL is displayed prominently on the campaign detail page with a copy button.

Landing Page Behavior by Status

Event-Type Campaign: 3-State Rendering

Event-type campaigns have enhanced rendering based on timing:

Upcoming State (before start date): Hero → Why Attend → Info → Countdown → Speakers → Schedule → Venue → Registration Form → Partners → Notify Form

Active State (during event): Hero (with "Happening Now") → Live Stream → Why Attend → Info → Schedule (with "now" indicator) → Speakers → Venue → Form (if capacity) → Partners → Testimonials

Completed State (after end date): Hero (recap) → Info → Gallery → Winners → Testimonials → Resources → Speakers → Partners → Notify Form (for next event)

10. Sub-Module: Campaign Submissions & Review

Purpose

Process and review form submissions from campaign landing pages, including approval workflows and promo code generation.

Access

Campaign Detail → Submissions tab

10.1 View Submissions

• Table view with columns: Submitted At, Submitter Info, Status, Reviewed By, Actions
• Filter by status: All / Pending Review / Approved / Rejected / Needs Info
• Search submissions
• Status count badges on each filter tab

10.2 Review a Submission

1. Click on a submission row to expand details
2. View all form field responses, uploaded files (selfie, ID card, documents)
3. Choose an action:

10.3 Generate Promo Code

After approving a submission:

1. Click "Generate Promo Code"
2. System generates a unique code using the campaign's promoCodePrefix
3. Code is linked to the submission (one-to-one)
4. Code type, value, and validity are based on campaign incentive settings
5. Approval email includes the generated promo code

10.4 Bulk Operations

• Select multiple submissions → Bulk Approve or Bulk Reject
• Requires MARKETING_SUBMISSIONS_REVIEW permission

10.5 Submission Data Flow

Reader submits form on landing page
  → POST `/api/marketing/campaigns/public/{slug}/submit`
  → Creates CampaignSubmission record
  → Increments campaign counters (totalSubmissions, pendingCount)
  → Upserts AudienceContact from form data (email, name, phone)
  → Admin reviews in Submissions tab
  → Approve → sends approval email → optionally generates promo code
  → Reject → sends rejection email with reason

11. Sub-Module: Campaign Invitations

Purpose

Send targeted email invitations to segmented audiences to drive campaign participation.

Access

Campaign Detail → Invitations tab

11.1 View Invitations

• List of all invitations for the campaign
• Status badges: Draft / Scheduled / Sending / Sent / Failed
• Delivery metrics per invitation: Recipient Count, Delivered, Opened, Clicked, Registered

11.2 Create Invitation

1. Click "New Invitation"
2. Select Segment: Choose from existing segments (which include audience contacts)
3. View segment member count to confirm audience size
4. Write Subject Line: Supports {{campaign_name}} variable
5. Compose Email Content: Rich text with variable support:
   • {{user_name}} — Recipient name
   • {{campaign_name}} — Campaign name (auto-resolved)
   • {{campaign_url}} — Landing page URL with UTM parameters
   • {{incentive_description}} — Incentive details
6. Preview: See rendered email with sample data
7. Choose action:
   • Save as Draft — Save without sending
   • Send Now — Send immediately
   • Schedule — Set a future date/time for automated send

11.3 Send Invitation

1. From a draft invitation, click "Send"
2. System resolves segment members at send time
3. Emails are dispatched using campaign_invitation template
4. Campaign URL includes UTM parameters: ?utm_source=email&utm_medium=invitation&utm_campaign={slug}&source=email_invite
5. Status transitions: draft → sending → sent (or failed)
6. Recipient emails are snapshotted on the invitation record for audit

11.4 Scheduled Invitations

• Scheduled invitations are picked up by the send-invitations cron job
• Processed when scheduledAt <= now and status is scheduled

11.5 Template Variable Resolution

The invitation composer resolves {{campaign_name}} to the actual campaign name in both the slider header and email content display.

12. Sub-Module: Email Campaigns

Purpose

Send template-based or custom HTML email campaigns to segmented audiences with scheduling and engagement tracking.

Access

Admin Console → Marketing → Email Campaigns

12.1 View Email Campaigns

• List with columns: Name, Subject, Segment, Status, Sent At, Open Rate, Click Rate
• Status tabs: Draft / Scheduled / Sending / Sent / Failed
• Count badges per tab

12.2 Create Email Campaign

1. Click "New Email Campaign"
2. Configure:
   • Name (required)
   • Subject Line (required, supports {{variable}} interpolation)
   • Email Template — select from existing templates OR provide custom HTML
   • Target Segment — select segment for audience targeting
3. Save as draft

12.3 Send Email Campaign

Send Now:

1. Open a draft email campaign
2. Click "Send Now"
3. System resolves segment members
4. Enforces newsletter opt-in check (unless forceSend=true)
5. Sends emails in batches via SendGrid/SMTP
6. Status: draft → sending → sent

Schedule:

1. Open a draft email campaign
2. Click "Schedule"
3. Set the scheduled date/time
4. Status: draft → scheduled
5. The send-scheduled-emails cron picks it up when due
6. Cron atomically claims the campaign (scheduled → sending) to prevent double-send
7. Status: sending → sent

12.4 Duplicate Campaign

• Click "Duplicate" to create a copy as a new draft
• Useful for recurring campaigns with slight modifications

12.5 Email Campaign Metrics

After sending, the campaign shows engagement metrics:

• Delivered: Emails successfully delivered
• Opened: Unique opens
• Clicked: Unique link clicks
• Bounced: Hard/soft bounces
• Unsubscribed: Recipients who unsubscribed

Metrics are updated via SendGrid/Mailchimp engagement webhooks in real-time.

12.6 Delete Email Campaign

• Only unsent campaigns (draft/scheduled) can be deleted
• Sent/sending campaigns cannot be deleted (for audit compliance)

13. Sub-Module: Newsletter Editions

Purpose

Author newsletter editions in Strapi CMS, manage their lifecycle, send them as email campaigns, and provide a reader-facing archive.

Architecture Note

Newsletter editions use a dual-storage approach:

• Strapi CMS: Source of truth for content authoring (rich text editing, cover images, SEO)
• Admin Console API: Acts as proxy to Strapi, bridges to Prisma EmailCampaign for email delivery

Access

Admin Console → Marketing → Newsletters

13.1 View Newsletter Editions

• List with status tabs: All / Draft / Published / Featured / Archived
• Search by title
• Columns: Title, Edition Number, Topic, Status, Publish Date

13.2 Create Newsletter Edition

1. Click "New Newsletter"
2. Fill in:
   • Title (required)
   • Edition Number (auto-incremented or manual)
   • Topic (for archive filtering)
   • Preview Text (teaser shown in archive cards)
   • Publish Date
   • Cover Image (via Media Picker)
   • HTML Content (rich text editor)
   • Plain Text Content (fallback for text-only email clients)
   • External Archive URL (optional, for linking to external archive)
3. Save (creates in Strapi as draft)

13.3 Publish Newsletter

1. Open a draft edition
2. Click "Publish"
3. Uses Strapi v5 publish action API
4. Edition becomes visible in the public newsletter archive at {READER_URL}/newsletters

13.4 Send Newsletter as Email Campaign

1. From the newsletters list, click "Send as Campaign" (or from edition detail page)
2. A modal appears:
   • Select Segment — choose target audience
   • Subject Line — defaults to edition title
3. Click Send
4. System:
   • Fetches full content from Strapi
   • Creates a Prisma EmailCampaign with newsletterEditionId for traceability
   • Dispatches emails to segment members
5. The email campaign appears in the Email Campaigns list for tracking

13.5 Reader Portal Newsletter Archive

• Accessible at {READER_URL}/newsletters
• Topic filter pills: Filter editions by topic
• Edition cards: Show edition number, featured badge, topic tag, title, publish date, preview text
• Pagination: Navigate through archive
• Individual edition page: {READER_URL}/newsletters/{slug} — renders full HTML content
• ISR: Archive page uses Incremental Static Regeneration with 5-minute revalidation

14. Sub-Module: Promotional Codes

Purpose

Create and manage discount codes for subscription plans. Promo codes can be admin-created (DiscountCoupon) or auto-generated from campaign submissions (PromotionalCode).

Access

Admin Console → Marketing → Promo Codes

14.1 Two Types of Promo Codes

14.2 Create Admin Coupon

1. Click "New Promo Code"
2. Configure:
   • Code (unique, e.g., SUMMER2026)
   • Description
   • Discount Type: Percentage or Fixed Amount
   • Discount Value (e.g., 20% or $10)
   • Linked Plan (optional, restrict to specific subscription plan)
   • Billing Interval (optional)
   • Max Uses (total redemption limit)
   • Max Uses Per User
   • Valid From / Valid To dates
   • Options: New subscribers only, applies to (FIRST_PAYMENT / N_CYCLES / ALL_RENEWALS), discount cycles, allow gift/bulk/institutional
3. Save

14.3 Campaign Promo Code Auto-Generation

When a campaign submission is approved and the campaign has incentive settings:

1. Admin approves submission → clicks "Generate Promo Code"
2. System generates a unique code: {promoCodePrefix}-{random}
3. Code is saved as PromotionalCode with:
   • Type: percentage, fixed, or trial_days (from campaign incentive settings)
   • Value: from campaign incentiveValue
   • Validity: from campaign promoValidityDays
   • Max redemptions: 1 (single use)
4. Code is linked to the submission record

14.4 Public Promo Code Validation & Redemption

Validate (POST /api/promo-codes/validate or POST /api/promo/validate):

• Checks both PromotionalCode and DiscountCoupon tables
• Returns discount type, value, validity
• Rate limited: 20 requests/minute/IP

Redeem (POST /api/promo/redeem):

• For trial_days: Atomically creates reader account + subscription in a transaction
• For percentage/fixed: Atomically claims redemption slot
• Rate limited: 5 requests/15 minutes/IP

15. Sub-Module: Conversion Surfaces

Purpose

Deploy promotional overlays (modals, banners, slide-ins, sticky notifications) on the Reader Portal with sophisticated targeting and trigger rules to drive reader actions.

Access

Admin Console → Marketing → Conversion Surfaces

15.1 Surface Types

15.2 Create Conversion Surface

1. Click "New Surface"
2. Configure:

Identity & Presentation:

• Name, Surface Type, Placement
• Title, Subtitle, Body Text
• Image URL
• Primary CTA (text + URL), Secondary CTA (text + URL)
• Background Color, Theme (light/dark/brand)

Conversion Goal:

• register, login, subscribe_paid, subscribe_newsletter, view_campaign, view_event, redeem_coupon, view_product, visit_pricing, custom_cta

Entity Links (optional):

• Linked Coupon (DiscountCoupon)
• Linked Plan (SubscriptionPlan)
• Linked Campaign (OutreachCampaign)
• Linked Event
• Linked Product
• Newsletter Slug

Targeting Rules (JSON):

• audiences: anonymous, registered, subscriber, newsletter_subscribed, newsletter_unsubscribed
• pageTypes: homepage, article, section, etc.
• deviceTypes: mobile, tablet, desktop
• includeUrls / excludeUrls: URL pattern matching
• contentTypes, sections, tags: Content-based targeting
• utmSource, utmMedium, utmCampaign: UTM parameter matching

Trigger Configuration:

• page_load — Show on page load (with optional delay)
• time_on_page — Show after N seconds
• scroll_depth — Show after scrolling to N%
• exit_intent — Show when mouse leaves viewport
• page_view_count — Show after N page views
• after_article_read — Show after scrolling to 100% of article
• manual — Programmatic trigger only

Frequency & Suppression:

• Frequency Limit + Unit (per session/day/week/month)
• Suppress After Dismiss (boolean)
• Suppress After Conversion (boolean)
• Suppress If Already Converted (boolean)

Scheduling:

• Status: draft, scheduled, active, paused
• Starts At / Ends At dates
• Priority (lower number = higher priority)

3. Save as draft

15.3 Activate Surface

1. Change status from draft → active (via PUT API)
2. Surface immediately begins displaying to eligible readers on the Reader Portal

15.4 Reader Portal Rendering

The conversion surface system uses a layered rendering architecture:

1. GlobalConversionSurfaces — Wraps the entire Reader Portal root layout
2. ConversionSurfaceProvider — React context that:
   • Detects device type (mobile/tablet/desktop)
   • Counts page views (stored in state, incremented per mount)
   • Fetches eligible surfaces from GET /api/public/conversion-surfaces/eligible
   • Filters through local suppression checks (localStorage for anonymous, server-side for authenticated)
   • Sorts by priority
   • Enforces slot-based conflict resolution: one modal at a time, one sticky at a time, banners can coexist
3. ConversionSurfaceRenderer — Evaluates trigger conditions and renders the appropriate surface component

Trigger Evaluation:

• page_load: Fires after optional triggerDelaySeconds
• time_on_page: Timer starts on mount, fires at triggerDelaySeconds
• scroll_depth: Monitors scroll position, fires when triggerScrollPercent is reached
• exit_intent: Listens for mouseout event leaving the viewport (desktop only)
• page_view_count: Compares provider's page view count against triggerPageViews
• after_article_read: Monitors scroll to 100% of content
• manual: Not automatically triggered

Frequency Enforcement:

• Anonymous readers: Client-side via localStorage (per-surface tracking)
• Authenticated readers: Server-side via ConversionEvent records

15.5 Analytics

Dual tracking approach:

1. Internal (ConversionEvent table): Stores every interaction with reader context (page, device, UTM, session)
2. GA4: Fires custom events for cross-platform attribution

Stats API (GET /api/marketing/conversion-surfaces/{id}/stats):

• Date range filtering
• Time series data
• Breakdowns by device, page, UTM
• Computed rates: CTR, conversion rate, dismiss rate, engagement rate

Denormalized counters on ConversionSurface model:

• impressionCount, clickCount, dismissCount, conversionCount
• Updated atomically on each event
• Used for fast list view display

15.6 Coupon Integration

Surfaces can link to DiscountCoupon records:

• Eligibility API validates coupon status (active, not expired, usage limit not reached)
• Reader Portal shows copyable coupon code with "Copy Code" button
• coupon_copied event tracked to both GA4 and internal analytics
• Coupon code passed to checkout URL as parameter

16. Sub-Module: Campaign Types

Purpose

Define and manage reusable campaign type categories that appear in the campaign creation dropdown.

Access

Admin Console → Marketing → Campaign Types

Features

• CRUD: Create, read, update, delete campaign types
• Fields: Name (unique), Slug (unique, auto-generated), Description, Icon (Lucide icon name), Active flag, Sort Order
• Seeded Defaults: 5 types seeded from the system enum: Student Outreach, Event Registration, Lead Generation, Institutional, General
• Usage: Campaign types appear in the campaign creation wizard and campaign edit form as a dropdown
• Deletion Protection: Cannot delete a type that is linked to existing campaigns

17. Cron Jobs & Automation

Overview

send-scheduled-emails

1. Finds all email campaigns with status = 'scheduled' and scheduledAt <= now
2. Atomically transitions status to 'sending' (prevents double-send on concurrent cron runs)
3. Resolves segment members
4. Sends emails via SendGrid/SMTP
5. Updates status to 'sent' or 'failed'

campaign-status

1. Finds active campaigns where endDate < now → transitions to 'completed'
2. Finds draft campaigns where endDate < now → transitions to 'archived'
3. Looks up CampaignNotifyRequest records for campaigns that just became active → sends notification emails using campaign_notify_new_campaign template

send-invitations

1. Finds invitations with status = 'scheduled' and scheduledAt <= now
2. Resolves segment members for each invitation
3. Sends invitation emails
4. Updates status to 'sent' or 'failed'

18. Webhook Integrations

SendGrid Engagement Webhook

Endpoint: POST /api/webhooks/sendgrid

Events Processed:

Authentication: ECDSA P-256 signature verification (optional, controlled by SENDGRID_WEBHOOK_VERIFICATION_KEY)

Mailchimp/Mandrill Engagement Webhook

Endpoint: POST /api/webhooks/mailchimp

Events Processed: send, open, click, hard_bounce, soft_bounce, spam, unsub

Authentication: HMAC-SHA1 signature verification (optional, controlled by MAILCHIMP_WEBHOOK_KEY)

URL Verification: GET /api/webhooks/mailchimp returns 200 OK for Mandrill webhook registration.

19. Reader Portal Rendering

Campaign Landing Pages

URL: {READER_URL}/campaigns/{slug}

Technology: Next.js App Router, Server Component with ISR (60-second revalidation)

Components (24 campaign section components):

Newsletter Archive

URL: {READER_URL}/newsletters

Components:

• NewsletterArchive — Topic filter pills, paginated edition grid
• NewsletterCard — Edition card with number badge, topic, date, preview
• NewsletterArchiveHeader — Page header
• Individual edition: {READER_URL}/newsletters/{slug}

Programs Discovery Page

URL: {READER_URL}/programs

Features:

• Browse past/ongoing/upcoming campaigns
• Filter by campaign type, status, institute, city, country
• Card grid with status badges, date ranges, type badges
• Links to campaign landing pages

Explore By Language

The homepage "Explore By Language" section (LanguageFilterSection, Figma utility-language-filter) is a horizontally-scrollable row of language cards linking to /languages/{slug}.

Languages are fetched dynamically rather than hardcoded:

1. If an admin has set a language override on the section (displayOptions.languages), that list is used as-is.
2. Otherwise the section calls GET /api/articles/languages (Reader Portal route, 5-minute ISR cache) which returns the distinct languages that actually appear on published articles.
3. If that call returns nothing or fails, it falls back to the built-in platform default list (Tamil, Bengali, Malayalam, Marathi, Hindi, Kannada, Telugu, Gujarati, English).

The practical effect: the language strip stays in sync with the content you actually publish, with no manual upkeep — a language only appears once at least one published article uses it.

Conversion Surfaces

Renders globally across all Reader Portal pages via GlobalConversionSurfaces in the root layout.

See Section 15.4 for detailed rendering behavior.

20. Business Logic & Rules

Campaign Validation Rules

• Campaign slug must be unique across all campaigns
• Start date must be before end date
• At least one form field required before publishing
• Status transitions follow a strict state machine (see Section 4)
• Cannot delete a campaign that has submissions (use archive instead)

Segment Resolution Rules

• Filters use AND logic between groups, OR logic within a group
• When source includes "audience contacts", queries both Reader and AudienceContact tables
• Members are resolved dynamically at query time (not cached lists)
• Segment cannot be deleted if used by active campaigns or invitations

Email Campaign Rules

• Cannot update or delete sent/sending campaigns
• Scheduled campaigns are atomically claimed by cron to prevent double-send
• Newsletter opt-in is enforced by default (unless forceSend=true)
• Template variables use Handlebars syntax: {{variable_name}}

Conversion Surface Rules

• Slot-based conflict resolution: Maximum one modal, one sticky notification active simultaneously; banners can coexist
• Priority: Lower number = higher priority; when multiple surfaces compete for a slot, highest priority wins
• Frequency capping: Configurable per session/day/week/month
• Suppression: Can suppress after dismiss, after conversion, or if already converted
• Targeting: AND between dimension types, OR within a dimension
• Soft delete: Archive instead of hard delete (preserves analytics history)

Promotional Code Rules

• Campaign-generated codes are single-use (maxRedemptions = 1)
• Admin coupons can have configurable max uses and per-user limits
• Validation checks: code exists, is active, not expired, usage limit not reached
• trial_days redemption atomically creates reader account + subscription
• Rate limiting on public validation (20/min) and redemption (5/15min)

Contact/Audience Rules

• Email must be unique across audience contacts
• Inactive contacts (isActive = false) are excluded from segments
• Unsubscribed contacts are excluded from non-forced email sends
• Auto-upsert from campaign submissions and newsletter signups is non-blocking (failures don't break primary flow)

21. End-to-End User Flows

Flow 1: Create and Launch an Outreach Campaign

1. Create Campaign Type (if needed)
   Marketing → Campaign Types → Add → "Conference"

2. Build Audience Segment
   Marketing → Segments → New Segment
   → Filter: Account Status = Active, Subscription = None
   → Save as "Non-Subscribers"

3. Create Campaign
   Marketing → Campaigns → New Campaign
   → Step 1: Name, Slug, Type, Dates
   → Step 2: Form Fields (Name, Email, Phone, Institution)
   → Step 3: Landing Page (Hero, Content, Success/Expired messages)
   → Step 4: Event Details (Speakers, Schedule, Venue) — if event
   → Step 5: Post-Event Content — skip for now
   → Step 6: Incentive (Free Trial, 30 days)
   → Step 7: Review → Create

4. Configure Landing Page Template
   Campaign Detail → Layout & Style tab
   → Select template → Save

5. Publish Campaign
   Campaign Detail → Click "Publish"
   → Validates → Status = Active
   → Copy landing page URL

6. Send Invitations
   Campaign Detail → Invitations tab → New Invitation
   → Select "Non-Subscribers" segment
   → Compose email → Send

7. Share on Social
   Campaign Detail → Social tab
   → "Create Social Campaign" → "Compose Post"
   → Pre-filled with campaign name/URL → Publish

8. Monitor
   Campaign Detail → Statistics tab → View submissions count
   → Submissions tab → Review & approve submissions
   → Generate promo codes for approved submissions

9. Complete Campaign
   After end date: Click "Complete"
   Add post-event content (gallery, winners, resources)
   Campaign page shows recap state

Flow 2: Newsletter Edition → Email Campaign

1. Create Newsletter Edition
   Marketing → Newsletters → New Newsletter
   → Author content in form
   → Save as draft

2. Publish
   Newsletter detail → Click "Publish"
   → Visible at `/newsletters/{slug}`

3. Send as Email Campaign
   Newsletters list → "Send as Campaign" button
   → Select target segment
   → Confirm subject line
   → Send

4. Track Engagement
   Marketing → Email Campaigns
   → Find campaign → View open/click/bounce metrics

Flow 3: Deploy a Conversion Surface

1. Create Coupon (optional)
   Marketing → Promo Codes → New Code
   → Code: "SAVE20", 20% off

2. Create Conversion Surface
   Marketing → Conversion Surfaces → New Surface
   → Type: Modal, Theme: Brand
   → Title: "Subscribe & Save 20%"
   → Link coupon: "SAVE20"
   → Goal: subscribe_paid
   → Targeting: anonymous + homepage + desktop
   → Trigger: exit_intent
   → Frequency: 1 per week
   → Suppress after conversion

3. Activate
   Set status to "active"
   → Surface appears to matching readers on Reader Portal

4. Monitor
   Conversion Surfaces list → View impression/click/conversion metrics
   → Detail → Stats → Time series, breakdowns

Known Limitations

Planned but Not Yet Implemented

Current Limitations

1. No real-time websocket notifications — Notification bell uses polling, not push
2. Newsletter content authoring requires Strapi — No built-in rich text editor for newsletters in Admin Console
3. Conversion surface preview — You cannot preview a surface's appearance in Admin Console before activating
4. Campaign form field types — No conditional logic (show/hide fields based on other field values)
5. Segment caching — Segments resolve dynamically on every query; large segments may have latency
6. Email campaign retry — Failed campaigns must be manually retried (no automatic retry)
7. Invitation tracking — Individual recipient open/click tracking depends on email provider webhook reliability
8. Conversion surface inline embed — Requires manual template configuration; no automatic content-aware positioning

FAQ