Newsletter & Mailing Lists — Forms
Newsletter & Mailing Lists — Forms & Input Specification
Reference technical blueprint: newsletter.md Slug:
newsletter· Module #18 · 6 sub-modules · ~10 forms
Periodicals + subscriber management + multi-channel distribution.
Important scope: Newsletter serves the general public, not only tenant members. Public sign-up forms with double-opt-in are first-class. Subscribers may be members (FK to members.id) or external email/phone.
Sub-module 1: Mailing Lists
Form 1.1 — Mailing List Setup
Purpose: Create a named list (e.g. "Monthly Newsletter", "Annadana Donors", "Festival Devotees"). Who fills: Tenant-admin / publications-admin. Rare — typically a few lists per tenant.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| List Name | Text | Yes | Unique per tenant | — | e.g. Monthly Newsletter |
| Slug (for public URL) | Text | Yes | URL-safe, unique | Auto-from-name | Public form lives at /newsletter/subscribe/<slug> |
| Description | Textarea | No | Shown on public form | — | What subscribers will receive |
| Frequency Hint | Dropdown | Yes | Daily · Weekly · Monthly · Quarterly · Festival-only · Ad-hoc | Monthly | Sets reader expectation |
| Default Channels | Multi-select | Yes | Email · WhatsApp · Postal | Subscriber can override | |
| Double Opt-in Required? | Checkbox | Yes | — | ☑ | DPDP / GDPR compliance |
| Public Archive Visible? | Checkbox | Yes | — | ☑ | Past issues at /newsletter/archive/<slug> |
| Active? | Checkbox | Yes | — | ☑ | — |
Submit action: Creates list; auto-creates a Comms audience-segment named newsletter:<slug>:active.
Related: Public sign-up at /newsletter/subscribe/<slug> (Form 2.1).
Sub-module 2: Public Subscribe Flow
Form 2.1 — Public Subscription Form (PUBLIC, no login)
Purpose: General public signs up for a mailing list. Lives at /newsletter/subscribe/<slug>.
Who fills: Anyone visiting the website.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| Name | Text | Yes | — | — | First + last (free-text) |
| Conditional | — | — | If Channel=Email | ||
| Phone (with country code) | Phone | Conditional | E.164 format | — | If Channel=WhatsApp/SMS |
| Postal Address | Textarea | Conditional | — | — | If Channel=Postal |
| Pincode | Text | Conditional | If Postal | — | — |
| City / State / Country | Text | Conditional | — | — | If Postal |
| Preferred Channel | Dropdown | Yes | From list's default channels | — | |
| Preferred Language | Dropdown | No | English · Hindi · Sanskrit · Kannada · Telugu · Tamil · Other | English | — |
| Captcha | Captcha | Yes | — | — | Anti-spam |
| Consent | Checkbox | Yes | — | ☐ | "I agree to receive newsletters and accept the privacy policy" — link required |
Submit action: Creates member_subscriptions row with status=pending. If list requires double-opt-in, sends confirmation email/WhatsApp with one-time link. Else activates immediately.
Form 2.2 — Double-Opt-In Confirmation Page (PUBLIC)
Purpose: One-click confirmation after public sign-up. Lives at /newsletter/confirm/<token>.
Display:
- "You're confirming your subscription to: "
- "as
Submit action: Token validated → status flips to active → welcome message sent.
Form 2.3 — Preference Centre (PUBLIC, link from every email)
Purpose: Subscriber views their subscriptions and changes channel / unsubscribes.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| Identity Token | URL token | Yes | One-time link from email | — | — |
| Per-list controls (loop): | |||||
| List Name | Read-only | — | — | — | — |
| Status | Dropdown | Yes | Active · Paused · Unsubscribed | Active | — |
| Channel | Dropdown | Yes | From list's defaults | Current | — |
| Pause Until | Date | Conditional | If Status=Paused | — | — |
| Unsubscribe All | Button | — | — | — | Single click; shows confirmation |
Submit action: Updates per-list state; logs to audit_events.
Sub-module 3: Issue Composition
Form 3.1 — Issue Compose
Purpose: Editor drafts an issue.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| Mailing List | Dropdown | Yes | — | — | — |
| Issue Title | Text | Yes | — | — | e.g. "Sri Datta Jayanti Special — Dec 2026" |
| Subject Line | Text | Yes | ≤ 100 chars (email subject) | Title | — |
| Body | Rich-text editor | Yes | — | — | Insert images, links, member-vars like {{name}} |
| Featured Image | File | No | JPG/PNG ≤ 5MB | — | Top banner |
| Sections | Multi-line builder | No | Drag-and-drop blocks | — | Each section: heading + body |
| Embedded Reports | Multi-select | No | From Reports module | — | E.g. "Last Quarter Donations" |
| Scheduled For | Datetime | Yes | Future | Now+1hr | — |
| Send Test To | No | — | Self | Test before scheduling |
Submit action: Saves as draft (status=draft). Goes through review (Form 3.2) before send.
Form 3.2 — Issue Reviewer Sign-off
Purpose: Second-pair-of-eyes approval before broadcast.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| Issue | Dropdown | Yes | Drafts pending review | — | — |
| Decision | Dropdown | Yes | Approve · Reject · Request Changes | — | — |
| Reviewer Comments | Textarea | Conditional | If Reject/Request | — | — |
| Schedule Override | Datetime | No | — | Author's chosen time | Reviewer can reschedule |
Submit action: Approve → queues for dispatch via Comms. Reject → returns to author with comments.
Sub-module 4: Subscriber Management (admin)
Form 4.1 — Subscriber List View
Purpose: Admin browses subscribers per list.
Filters: List · Status (active/pending/paused/unsubscribed) · Channel · Date subscribed
Display: Email/phone, name (if known), member-link (if member), source (public_form / admin_import / qr / event), subscribed_at, last engaged_at
Form 4.2 — Bulk Subscriber Import (admin)
Purpose: CSV import for migrating existing list.
| Field | Type | Required | Options / Validation | Default | Help |
|---|---|---|---|---|---|
| Target List | Dropdown | Yes | — | — | — |
| CSV File | File upload | Yes | Headers: email, phone, name, channel | — | Template downloadable |
| Skip Double Opt-in? | Checkbox | Yes | — | ☐ | Only check if migrating verified list — log if used |
| Default Channel | Dropdown | Yes | — | For rows without channel | |
| Dry-run Preview | Button | — | — | — | Shows first 10 rows + validation errors |
Submit action: If dry-run, shows preview. Else inserts. Logs all imports to audit.
Sub-module 5: Engagement Analytics
Form 5.1 — Issue Engagement Report (read-only)
Purpose: See how an issue performed.
Display fields: - Issue title, list, sent_at, recipients (total) - Delivered (count + %), Opens (count + %), Clicks (count + %), Bounces, Unsubscribes - Top 10 clicked links (URL + count) - Engagement timeline graph (opens over hours/days) - Per-channel breakdown (email vs WhatsApp vs postal)
Sub-module 6: Public Issue Archive
Form 6.1 — Public Archive Browser (PUBLIC if list.archive_public=☑)
Purpose: Anyone can browse past issues. Lives at /newsletter/archive/<list-slug>.
Display: Paginated list of issues — title, sent_at, link to full HTML rendering. Search by title/keyword.
Workflow
Public subscriber: visits /newsletter/subscribe/<slug> → fills Form 2.1 → confirmation email → clicks Form 2.2 → status active → starts receiving issues. Editor: drafts Form 3.1 → submits for review → reviewer approves Form 3.2 → Comms dispatches per channel → engagement tracked Form 5.1. Members can also be subscribed via the Members Suite directly (admin path). Newsletter delegates ALL delivery to the Comms Service — same template engine, same audit log.