campaigns

The Campaigns submodule owns the `campaign` record itself: its content (subject, HTML/plain-text body, optional template reference), its target recipient list, its delivery profile, and its lifecycle state machine. A campaign is created in `draft` status and moves through `scheduled` → `sending` → `completed` (or `paused`, `canceled`, `failed`) as CampaignDispatchService drives it forward. Only campaigns in `draft`, `canceled`, or `failed` status can be deleted, which protects historical delivery data for anything that has actually gone out.

Starting a campaign (`POST /campaign/:id/start`, aliased at `/send`) is the most involved operation in the module. CampaignDispatchService first validates that the campaign has a mail delivery profile (an Integration Profile), a recipient list, and non-empty content, and — when the `campaign.unsubscribe.required` setting is enabled — that the content includes the `{{unsubscribeUrl}}` placeholder. It then pulls the recipient list, deduplicates by normalized email, and cross-references the global suppression list before ever touching the database in a write transaction. Inside a single transaction it upserts one `campaign_message` row per eligible recipient (skipping suppressed/unsubscribed/bounced ones as `skipped`, and reusing rows that already exist to avoid duplicating in-flight sends on resume), then updates the campaign counters and flips status to `sending`. Only after the transaction commits does it enqueue one queue job per pending message via `CampaignEmailWorkerService` — or, if `campaign.queue.enabled` is turned off, send every message inline and synchronously within the same request, reporting per-recipient progress through a Notification record.

Pausing and resuming only touch the campaign status; the underlying messages and their queue jobs are left alone, so a resumed campaign continues from wherever the in-flight queue left off rather than re-enqueuing already-sent messages. Canceling sets `status: canceled`, which the worker reads at send time to skip remaining messages without deleting them. Duplicate creates a new draft from an existing campaign's content and configuration, explicitly resetting every delivery counter, timestamp, and the schedule so the copy starts clean.

The global dashboard (`GET /campaign/dashboard`) and per-campaign dashboard (`GET /campaign/:id/dashboard`) are read-only aggregation endpoints backed by CampaignDashboardService: status counts across all campaigns, messages sent today, pending/queued backlog, 24h failure counts, suppression/unsubscribe totals, and a day-bucketed send history for the last 7/30 days, plus rate-limit context (daily cap and remaining capacity) sourced from CampaignRateLimitService. `GET /campaign/:id/status` is a lighter combination of the raw campaign record with aggregated message-status counts, useful for polling without pulling the full dashboard payload. Every state transition also writes an audit row via CampaignEventService, exposed at `GET /campaign/:id/events`.