# email-sequencer

Email drip-sequence and cadence designer for sales & lifecycle marketing: buildSequence turns a goal (cold-outreach, onboarding, re-engagement, trial-nurture, webinar, abandoned-cart, renewal...


An intelligent microservice adapter pack that designs email drip sequences and send cadences for
sales engagement and lifecycle marketing. Every tool has a deterministic, offline heuristic/template
core; the generative tools (`buildSequence`, `previewStep`) additionally use an optional LLM path to
rewrite subjects/copy and silently fall back to the templates when no model is reachable. Hybrid
results are tagged `{ mode: 'heuristic' | 'llm' }`.

## Tools

| Tool | What it does |
|---|---|
| `buildSequence` | Turns a `goal` (cold-outreach, onboarding, re-engagement, trial-nurture, webinar, abandoned-cart, renewal, upsell, event-followup, or free text) into a multi-touch drip with day offsets, channels, subject lines and body outlines. **Hybrid.** |
| `addBranch` | Forks an existing `sequence` on a `condition` (opened / not-opened / clicked / replied / no-response / bounced / unsubscribed) into a recommended branch path, with an exit policy. |
| `cadence` | Spaces N `touches` over a `windowDays` window using a `curve` (linear, front-loaded, back-loaded, fibonacci) and returns day offsets + gaps. |
| `previewStep` | Renders one step's subject, preview text, CTA and estimated read time. **Hybrid.** |
| `followupTiming` | Recommends the next-send delay, priority and best send window from prior `engagement` signals. |

## Usage

```js
import pack from './index.js';

// Build a 5-touch cold-outreach drip
const seq = await pack.adapters.buildSequence({ goal: 'cold-outreach', steps: 5, audience: 'CTO', product: 'Leumas' });
// -> { mode, goal, tone, stepCount, totalDays, sequence: [{ step, dayOffset, channel, subject, bodyOutline, cta }, ...] }

// Fork it when a lead clicks
pack.adapters.addBranch({ sequence: seq.sequence, condition: 'clicked', afterStep: 2, product: 'Leumas' });

// Recommend when to follow up next
pack.adapters.followupTiming({ engagement: { opened: true, clicked: true, lastOpenHour: 8 } });
```

## LLM / hybrid mode

Offline (default) everything runs on deterministic templates. When an OpenAI-compatible endpoint or a
local Ollama server is configured (see `../_shared/llm.js`), `buildSequence` and `previewStep` ask the
model to rewrite only the copy (subjects + body lines) while keeping the heuristic's day offsets,
channels and structure. Any model failure falls back to the template core — a down model never throws.

## DRY boundary notes

- Not a scheduler: day offsets are plain integers. `cron` owns interval-string parsing (`'5m'`);
  `datetime`/`ical` own calendar math and event files. This pack plans *what to send and when*, not
  wall-clock scheduling.
- Not a text toolkit: `nlp` / `a-text` own raw string transforms. Copy here is domain-specific
  marketing templating, not general text processing.
- Self-contained: no cross-pack imports except `../_shared/llm.js`.


---
Source: shared/engines/adapters/domain/email-sequencer/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/email-sequencer