Email Notification Service
Relevant source files
The following files were used as context for generating this wiki page:
The Email Notification Service is a backend utility and API suite designed to handle outgoing communications for the Lou Gehrig Fan Club (LGFC) platform. It primarily facilitates user onboarding through welcome emails and alerts administrators regarding new community join requests.
The service is built to integrate with the MailChannels API for transactional delivery and utilizes Cloudflare D1 for managing dynamic email content. It supports both plain text and basic HTML formatting, ensuring compatibility across various email clients while allowing administrators to customize copy via an authenticated admin interface.
Sources: functions/_lib/email.ts, context.md:12-15
System Architecture
The service operates as a library within the Cloudflare Pages Functions environment. It provides high-level functions for specific notification types and a low-level wrapper for the MailChannels API.
Core Components
- MailChannels Provider: The primary delivery mechanism. It requires an API key and specific environment variables to function.
- Content Management: Welcome email copy is stored in a Cloudflare D1 database, allowing for versioned updates without code changes.
- Formatting Utilities: Internal helpers convert Markdown content into both plain text and sanitized HTML to provide multi-part MIME support.
Sources: functions/_lib/email.ts:25-78, migrations/0023_welcome_email_content.sql:4-10
The diagram above illustrates the data flow from a system trigger (like a user joining) through the internal formatting logic to the external MailChannels provider.
Sources: functions/_lib/email.ts:35-64
Email Types and Logic
The service handles two primary categories of emails: automated user welcomes and administrative alerts.
Welcome Email
The sendWelcomeEmail function generates a personalized message for new members. It attempts to fetch a custom "intro" Markdown string from the database; if unavailable, it falls back to hardcoded default text.
Sources: functions/_lib/email.ts:109-152
Admin Notifications
The sendAdminJoinNotification function alerts project administrators when a new user submits a join request. It sends detailed metadata, including the request ID and timestamp, to a comma-separated list of administrative emails configured in the environment.
Sources: functions/_lib/email.ts:154-192
Data Flow for User Questions
When a user submits a question via the /ask interface, the system logic dictates an email response to the submitter following administrative review.
Sources: src/app/ask/page.tsx:14-16, lgfc-lite-configure-remaining.sh:16-24
The sequence diagram shows the administrative process of updating email copy followed by the standard retrieval and sending flow.
Sources: functions/api/admin/welcome-email.ts:38-58, functions/_lib/email.ts:109-152
Configuration and Environment
The service requires several environment variables to be defined in the Cloudflare Pages dashboard for successful operation.
| Variable | Requirement | Description |
|---|---|---|
MAILCHANNELS_ENABLED | Required | Must be set to "1" to enable the provider. |
MAILCHANNELS_API_KEY | Required | API key for MailChannels authentication. |
MAIL_FROM | Required | The sender address (e.g., "Name email@domain"). |
MAIL_ADMIN_TO | Optional | Comma-separated list of admin recipients. |
MAIL_REPLY_TO | Optional | Global reply-to address for outgoing mail. |
NEXT_PUBLIC_SITE_URL | Optional | Used to generate links back to the site. |
Sources: functions/_lib/email.ts:25-34, functions/_lib/email.ts:71-78
Database Schema
Welcome email content is persisted in the welcome_email_content table to allow for administrative edits without redeploying the site.
| Field | Type | Description |
|---|---|---|
id | INTEGER | Primary Key, Autoincrement. |
title | TEXT | Descriptive title for the email version. |
body_md | TEXT | The Markdown content of the email body. |
status | TEXT | 'posted' (active) or 'hidden' (archived). |
updated_at | TEXT | ISO8601 timestamp of last update. |
Sources: migrations/0023_welcome_email_content.sql:4-10
Implementation Details
Markdown Conversion
The service implements a lightweight Markdown parser to ensure content consistency across text and HTML formats.
// functions/_lib/email.ts:80-87
function mdToPlain(md: string): string {
return String(md || '')
.replace(/^#+\s+/gm, '')
.replace(/\*\*(.*?)\*\*/g, '$1')
.replace(/\*(.*?)\*/g, '$1')
.replace(/`([^`]*)`/g, '$1')
.trim();
}
Sources: functions/_lib/email.ts:80-87
Administrative API
The /api/admin/welcome-email endpoint provides the interface for managing content.
- GET: Retrieves the currently "posted" email content.
- POST: Sets existing content to "hidden" and inserts a new "posted" record.
Sources: functions/api/admin/welcome-email.ts:16-58
Summary
The Email Notification Service provides a robust foundation for transactional communication within the LGFC project. By decoupling email content from the codebase via Cloudflare D1 and utilizing a standardized provider (MailChannels), the system allows for flexible administrative control and reliable delivery of user-facing and internal notifications.