# Sequences Module

## Purpose

Multi-step B2B email outreach (follow-ups) separate from one-time **Campaigns**.

## Concepts

- **Campaign** — single broadcast send; KPIs: opens, clicks
- **Sequence** — timed multi-step outreach; KPIs: replies, meetings, conversion

## Models

- `Sequence` — segment, mailbox, stop rules, aggregate stats
- `SequenceStep` — template, delay days, per-step stats
- `SequenceRecipient` — enrolled contact with current step, next send, status
- `SuppressionList` — global email suppression (unsubscribe, bounce, complaint)

## Recipient enrollment

On activate / generate:

1. Load segment members via `getSegmentMembers` (uses `dedupeSegmentMembers`)
2. Filter: valid + catch-all + role-based emails
3. Skip suppressed, invalid, disposable
4. Dedupe by `normalizedEmail`
5. Prevent duplicate enrollment in same active sequence

## Execution

`runDueSequenceSteps()` (cron):

- Active sequences only
- Recipients `status=waiting` and `nextSendAt <= now`
- Send via existing SMTP/transport
- Record `EmailSendHistory` with `messageType=sequence`
- Advance step or mark completed

## Stop rules

| Rule | Default | Effect |
|------|---------|--------|
| stopOnReply | true | Real replies stop sequence; auto-replies do not |
| stopOnClick | false | Click tracking stops future steps |
| stopOnOpen | false | Open tracking stops future steps |

## API

See `docs/03-api-specification.md` — Sequences section.

## UI

- `/sequences` — list
- `/sequences/new` — builder
- `/sequences/[id]` — dashboard (stats, steps, recipients)