Email campaign management with automation engine, template library, suppression lists, rate limiting, and trigger-based workflows

Email Marketing

The email marketing system supports campaign sending, automation workflows, template management, suppression lists, and rate-limited delivery. It handles both marketing campaigns and transactional emails (order confirmation, shipping notifications, etc.).

Architecture

client.ts

sender.ts

types.ts

campaign-sender.ts

automation-engine.ts

automation.ts

suppression.ts

rate-limit.ts

queue.ts

template-library.ts

templates.ts

logger.ts

page.tsx

actions.ts

Email Types

The system handles these email categories:

Type	Description
`order-confirmation`	Sent after successful payment
`shipping-notification`	Sent when order ships with tracking
`delivery-confirmation`	Sent on delivery with feedback link
`contact-form`	Internal notification for contact submissions
`welcome`	New user registration
`newsletter`	Marketing newsletter
`abandoned-cart`	Cart recovery email
`fundraiser-followup`	Fundraiser campaign follow-up

Automation Engine

The automation engine (lib/email/automation-engine.ts) processes trigger-based email workflows. Supported triggers:

type AutomationTriggerType =
  | 'USER_REGISTERED'
  | 'ORDER_PLACED'
  | 'ORDER_SHIPPED'
  | 'ORDER_DELIVERED'
  | 'ABANDONED_CART'
  | 'LOYALTY_POINTS_EARNED'
  | 'LOYALTY_TIER_UPGRADE'
  | 'SUBSCRIPTION_CREATED'
  | 'BIRTHDAY'
  | 'REENGAGEMENT'
  | 'LOW_STOCK'
  | 'CUSTOM'

Enrollment Flow

Trigger Fires

An event occurs (e.g., ORDER_PLACED) and calls enrollInAutomation().

Find Matching Automations

The engine queries all active automations for the trigger type.

Create Enrollment

For each matching automation, an AutomationEnrollment record is created (or reactivated if previously completed). The first step's delay is calculated.

Process Steps

A cron job calls processDueAutomationSteps() to send emails for enrollments whose nextStepAt has passed. After sending, it advances to the next step or marks the enrollment as completed.

Delay Support

Each automation step has a configurable delayHours property. The engine calculates nextStepAt by adding the delay to the current time.

Campaign Sender

The runCampaignSender() function (lib/email/campaign-sender.ts) processes lead-generation email campaigns:

Loads the campaign and its template
Fetches leads with status CONTACT_FOUND and valid email
For each lead:
- Substitutes template variables ({{school_name}}, {{contact_name}}, {{sport}}, etc.)
- Sends the email via the email sender
- Updates lead status to EMAIL_SENT or EMAIL_FAILED
- Emits progress events via the scraper event bus

Suppression Lists

The checkSuppression() function (lib/email/suppression.ts) checks whether an email address should be excluded from sending (unsubscribed, bounced, or complained).

Rate Limiting

The lib/email/rate-limit.ts module enforces sending rate limits to prevent provider throttling and maintain deliverability.

Campaign progress is emitted in real-time via the scraper event bus, allowing the admin UI to show live sending status with per-lead progress updates.

How is this guide?

Email Marketing

On this page