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

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

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

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 → SMTP Status. Should show configured: true.

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.

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 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.

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 now 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 now correctly resolves {{campaign_name}} to the actual campaign name in both the slider header and email content display. This was fixed as part of the marketing feature review.

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

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 to Archive
   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