recipient-lists

The Recipient Lists submodule models `campaign_recipient_list`, the audience container a campaign points at via `recipient_list_id`. Every list carries a unique, validated slug (lowercase letters, numbers, hyphens, minimum 2 characters — auto-generated from the name if not supplied), a `source` classification ("manual" | "import" | "crm" | "mixed") that reflects how its recipients were populated, and rolled-up counters (`total_recipients`, `total_active`, `total_unsubscribed`, `total_suppressed`, `total_invalid`) that CampaignRecipientListService recalculates after every mutation rather than computing on read. All routes are dual-mounted under both `/campaign/lists/*` and `/campaign/recipient-lists/*` — the controller registers each handler twice with NestJS's multi-decorator support — so both naming conventions resolve identically; this documentation uses `/campaign/recipient-lists/*` as the canonical form.

Recipients can be added to a list three ways. Inline JSON (`POST .../recipients` with an array of `{ email, name?, ... }` objects or a single `{ email }` shorthand) upserts by email within the list. CRM sync (`person_ids` in the same endpoint) resolves each CRM Person's primary EMAIL-type contact, skipping people with no valid email and reporting them back in a `skipped` array, then flips the list's `source` to "mixed" (or "crm" if every recipient came from CRM) once at least one person is added. CSV import is a two-step flow: `POST .../recipients/import/preview` parses the uploaded file (custom hand-rolled CSV parser supporting both comma and semicolon delimiters and quoted fields, capped at 10 MB / enforced again at 5000 data rows) and returns detected columns plus a 20-row sample without persisting anything; `POST .../recipients/import` takes the same file plus a JSON `mapping` of CSV columns to recipient fields and performs the actual upsert-by-email, optionally linking each imported row to an existing CRM company via `company_id`.

Public signup (`POST /campaign/lists/:slug/signup`, unauthenticated) lets a list opt into self-service subscription. It only works when `allow_public_signup` is true on the list; when `enable_captcha` is also true, the configured CAPTCHA Integration Profile (reCAPTCHA, Cloudflare Turnstile, or Altcha) is invoked to validate the submitted `captcha_token` before the email is upserted. This is the typical entry point for embeddable newsletter signup forms.

The submodule also hosts the campaign realtime cursor (`GET /campaign/realtime/cursor`, `GET /campaign/realtime/stream`): every list mutation calls `CampaignRealtimeService.publish()`, bumping an in-memory sequence counter that admin UIs poll or subscribe to over Server-Sent Events to know when to refetch list data, without the server tracking per-client state.