Flashrev Mailer

SKILL.md

---
name: flashrev-mailer
description: Use this skill when an AI agent needs to plan, build, commit, monitor, or follow up on FlashRev-powered email outreach via the flashrev-mailer npm CLI (v2.0+). Triggers on requests involving cold email, outreach campaigns, multi-step follow-up sequences, AI auto-reply, prospect reply triage, or mailbox-pool drip sending. The CLI delegates send timing and reply tracking to the FlashRev backend sequence engine; live sends require explicit per-batch user approval; AI auto-reply prompts must be shown verbatim and approved before enabling. Agents should invoke with FLASHREV_MAILER_AI_MODE=1 (or --ai-mode) so all list/view outputs and errors are JSON-structured.
---

# FlashRev AI Mailer (v2.0.1)

Use the `flashrev-mailer` CLI to build personalized email sequences with
FlashRev mailbox pools, multi-step follow-up, event tracking (open/click/reply),
and optional LLM auto-reply. v2 delegates send timing and reply tracking to
the FlashRev backend; the CLI orchestrates building, commit, and inspection.

## Security posture

This skill creates and runs outbound email campaigns. The following
constraints apply to every workflow and are non-negotiable:

- **API key** lives only in the operator's shell environment
  (`FLASHREV_API_KEY` or the name set via `flashrev.apiKeyEnv`). It is never
  written to `.flashrev/config.json`, campaign exports, send logs, or chat
  output.
- **Live sending requires explicit human approval per batch.** The agent must
  run `--dry-run --yes` first, show rendered drafts and the destination
  mailbox to the user, and only proceed with `--live --yes` after the user
  approves drafts, schedule, and recipient set. The agent never auto-escalates
  batch size, never auto-resumes after pause without confirmation.
- **`ai-auto-reply enable` is high-risk.** Once enabled, the LLM will reply to
  prospects on the user's behalf using the saved prompt. The agent must:
  1. Show the full prompt verbatim to the user before calling `enable`
  2. Never write or modify the prompt without the user's explicit text
  3. Default to `disable` if there is any ambiguity
- **`pause` / `resume`** change production state. Confirm with the user before
  running either.
- **`reply --mail-id <ID>`** sends a real email to a prospect. Show the user
  the prospect's identity (from `inbox`) + the proposed reply body before
  sending.
- **`reschedule`** changes when emails go out. Confirm new window with user.
- **`send --live --send-now`** bypasses the working-time-window (sends step 1
  immediately, may include weekends or off-hours). Confirm with user before
  using.
- **`delete`** is irreversible. Even with `--yes`, list what will be deleted
  (local path + sequenceId + contact/step counts) in chat and get explicit
  confirmation from the user. Already-sent emails are not recalled.
- **Recipient gating**: only `emailSyntaxValid=true` contacts are committed.
  `send --live` triggers backend deliverability check automatically (dispatch-svc
  EmailVerifyService); undeliverable contacts are flagged errorContacts and skipped.
  `validate` is optional and only useful as a pre-commit preview for cold lists.
- **Failure mode is stop-and-ask**, not retry-with-different-input. If a
  prerequisite or confirmation is missing, halt the workflow and surface the
  gap to the user.

## Agent invocation convention

Agents calling this CLI should set **either**:

- Environment variable: `FLASHREV_MAILER_AI_MODE=1` (recommended; once per shell)
- Per-call flag: `--ai-mode` on every invocation

When enabled, the CLI **forces JSON output** on `list / outbox / inbox /
status / mailboxes / ai-auto-reply show / export` AND **wraps errors in JSON**
to stderr:

```json
{ "error": { "code": "...", "message": "...", "remediation": "..." } }
```

Without ai-mode, output is human-formatted tables — fine for users at a
terminal, fragile for agents to parse.

## Prerequisites

These must be set up by the **human operator**. The agent's role is to
**verify** each one and **guide the user** to fix anything missing — never
attempt to install software, generate API keys, or modify the shell
environment unattended.

- **Node.js ≥ 20** is on `PATH`.
- **CLI is installed globally**: `npm install -g flashrev-ai-mailer`. Verify
  with `flashrev-mailer --help`. Confirm version 2.x:
  `flashrev-mailer --help 2>&1 | head -1` should not look like the v1 single-shot CLI.
- **FlashRev API key** generated at
  https://info.flashlabs.ai/settings/privateApps and exported as
  `export FLASHREV_API_KEY="..."`. Persist in `~/.zshrc` or `~/.bashrc` per
  user preference. Never persist inside any config file.
- **Base URL initialized** once per workspace:
  `flashrev-mailer init --base-url "https://open-ai-api.flashlabs.ai"` (or
  the test/staging URL provided by your FlashRev team).
- **Outbound network access** to the FlashRev API host.
- **Workspace is writable** — campaign state and inbox cache live under the
  current working directory at `.flashrev/`.

Always run `flashrev-mailer doctor --check-api` before the first command.
This verifies endpoints AND triggers backend lazy-init of a default schedule
("Default Business Hours") for new accounts. If a check fails, **stop the
workflow, tell the user the exact missing prerequisite, and wait** — do not
proceed to `import` / `send` until the user reports it resolved.

## Required confirmations

Each item below is a business decision the agent must explicitly align with
the user before proceeding — do not assume defaults:

- Contact source approved (CSV, TSV, public CSV URL, Google Sheets export,
  Clay export).
- The email column and personalization variables are understood. Personalization
  uses `{{ FirstName }}` / `{{ LastName }}` / `{{ Company }}` / `{{ Title }}`
  syntax (displayProperty names from the FlashRev contact property whitelist).
- Campaign goal, offer, tone, sender identity, call-to-action approved.
- For multi-step follow-up: each step's content, `--delay-days`, and whether
  it's a reply (same thread, no subject) or a new thread are confirmed.
- Sending schedule (timezone + window + weekdays + holidays-skip policy)
  approved.
- **AI auto-reply prompt** (if used) approved verbatim. Show the full prompt
  text to the user before `ai-auto-reply enable`. The prompt is ≤ 2000 chars.
- User has reviewed drafts (`--dry-run`) and explicitly approved committing
  (`--live`).

## Workflow A — Single-step campaign (v1 style, still works)

```bash
flashrev-mailer doctor --check-api
flashrev-mailer mailboxes                                     # pick an addressId
flashrev-mailer import --campaign CAMPAIGN_ID --source contacts.csv
flashrev-mailer validate --campaign CAMPAIGN_ID --limit 200   # optional (backend auto-checks on send --live)
flashrev-mailer draft  --campaign CAMPAIGN_ID \
    --subject "Quick idea for {{ Company }}" \
    --body    "Hi {{ FirstName }}, ..."
flashrev-mailer send   --campaign CAMPAIGN_ID --dry-run --yes --mailbox ADDR_ID  # SHOW USER
# After user approves drafts:
flashrev-mailer send   --campaign CAMPAIGN_ID --live --yes --mailbox ADDR_ID
flashrev-mailer status --campaign CAMPAIGN_ID
```

The agent shows the user the dry-run table and waits for explicit "yes,
send" before `--live`.

## Workflow B — Multi-step follow-up

```bash
flashrev-mailer import --campaign CAMPAIGN_ID --source contacts.csv

# Step 1 (new thread)
flashrev-mailer draft --campaign CAMPAIGN_ID \
    --subject "Hi {{ FirstName }}" --body "..."

# Step 2 (3-day follow-up, same thread, no subject — backend uses "Re: ...")
flashrev-mailer draft --campaign CAMPAIGN_ID --step 2 --delay-days 3 \
    --reply-to 1 --body "Just following up..."

# Optionally step 3 etc — use --step N --delay-days N --reply-to <prev>
flashrev-mailer send  --campaign CAMPAIGN_ID --dry-run --yes --mailbox ADDR_ID
# User approves drafts + delay structure:
flashrev-mailer send  --campaign CAMPAIGN_ID --live --yes --mailbox ADDR_ID
flashrev-mailer status --campaign CAMPAIGN_ID
```

**Rules the agent must enforce when building follow-up:**
- `--reply-to N` requires step N to already exist; if not, draft step N first.
- `--reply-to N` rejects `--subject` (backend auto-sets `Re: <step N subject>`).
- Confirm with user: "step 2 will be sent N days after step 1 unless the
  prospect replies first — is that what you want?"

## Workflow C — AI auto-reply

LLM-driven replies trigger when prospects respond, using the prompt the user
provides. **Independent** from `prospectRepliesEnabled` (which stops the
sequence on reply). The two can be combined.

```bash
# At commit time (all params on the send command):
flashrev-mailer send --campaign CAMPAIGN_ID --live --yes --mailbox ADDR_ID \
    --ai-auto-reply --ai-auto-reply-prompt "You are a friendly SDR..."

# Or after commit (REQUIRES TWO-STEP FLOW — see below):
# Step 1: probe — show the prompt to the user (CLI prints to stderr, then errors out)
flashrev-mailer ai-auto-reply enable  --campaign CAMPAIGN_ID --prompt "..."
# → CLI prints the full prompt to stderr + a warning + errors out

# Step 2: confirm — user has reviewed and approved; agent adds --yes
flashrev-mailer ai-auto-reply enable  --campaign CAMPAIGN_ID --prompt "..." --yes

flashrev-mailer ai-auto-reply show    --campaign CAMPAIGN_ID
flashrev-mailer ai-auto-reply disable --campaign CAMPAIGN_ID --yes  # prompt preserved; --yes required
flashrev-mailer ai-auto-reply enable  --campaign CAMPAIGN_ID --yes   # reuses prompt; --yes still required
```

**Mandatory two-step flow for `enable`** (CLI-enforced, not just a guideline):

1. **Probe step**: agent runs `enable ... --prompt "..."` **without `--yes`**.
   CLI will print the full prompt + warning to stderr and error out.
2. **Show stderr output to the user verbatim**, get explicit "yes I approve this prompt".
3. **Confirm step**: agent re-runs `enable ... --prompt "..." --yes`.

**Hard agent rules:**
- Never invoke `ai-auto-reply enable ... --yes` in a single call without first
  showing the user the probe-step output. The CLI's two-step flow exists so this
  cannot happen silently.
- Never paraphrase or auto-generate prompts. The user supplies the exact text.
- If the user asks "make a prompt for me", help them draft it conversationally,
  but only call `enable` after they confirm the final text.
- `disable` also requires `--yes` (changes production sequence behavior).

## Workflow D — Triage replies, reply directly

After `send --live`, replies will arrive over hours/days. The agent helps the
user triage:

```bash
flashrev-mailer inbox --campaign CAMPAIGN_ID                  # see all replies
flashrev-mailer inbox --campaign CAMPAIGN_ID --sentiment positive  # only positives
flashrev-mailer inbox --campaign CAMPAIGN_ID --intent Interested

# To reply to a specific message:
flashrev-mailer reply --mail-id <MAIL_ID> --body "Thanks {{...}}"
# (MAIL_ID is the first column of `inbox` output)

# Mark as read without replying:
flashrev-mailer inbox --mark-read <MAIL_ID>

# View full event timeline for a sent message:
flashrev-mailer outbox --view <MAIL_ID>
```

**`reply` rules:**
- Show the user the inbox row first (from / snippet / sentiment / intent).
- Show the user the proposed reply body and wait for "yes".
- `reply` sends to the prospect's email (preserves thread).

## Workflow E — Operational control

```bash
flashrev-mailer pause   --campaign CAMPAIGN_ID    # stop future steps
flashrev-mailer resume  --campaign CAMPAIGN_ID    # resume

flashrev-mailer list                              # all local campaigns
flashrev-mailer list --remote                     # also pull backend sources=ai_mailer

flashrev-mailer steps list   --campaign CAMPAIGN_ID           # view current step list
flashrev-mailer steps remove --campaign CAMPAIGN_ID --step N  # delete step N (effective at next send --live)

flashrev-mailer reschedule --campaign CAMPAIGN_ID \
    --send-start 09:00 --send-end 18:00 --weekdays mon-fri \
    --timezone "America/New_York"   # or numeric id: --timezone 22

# Add contacts to existing campaign (default append; --overwrite to clear entire campaign)
flashrev-mailer import --campaign CAMPAIGN_ID --source new-contacts.csv
flashrev-mailer send   --campaign CAMPAIGN_ID --live --yes

# Delete a campaign (irreversible, --yes required)
flashrev-mailer delete --campaign CAMPAIGN_ID --yes                  # default: local + backend
flashrev-mailer delete --campaign CAMPAIGN_ID --keep-local --yes     # backend only
flashrev-mailer delete --campaign CAMPAIGN_ID --keep-remote --yes    # local only
```

`reschedule` creates a private schedule and applies it; existing schedules
referenced by other sequences are not touched.

`steps remove` takes effect on the next `send --live` via sequence/edit's
full-replace semantics — already-sent emails are not recalled; contacts on
the deleted step auto-shift to the next step.

### Scheduling timezone (default behavior)

If `--timezone` is omitted, the CLI resolves in this order:

1. **Your FlashRev profile's `timezoneId`** (auto-fetched from
   `GET /engage/api/v1/user/setting/profile`, cached 24h at
   `.flashrev/profile-cache.json`)
2. **Fallback `id=22 America/New_York`** (when profile is unreachable)

`--timezone` accepts two formats:
- Numeric id (recommended for scripts, e.g. `--timezone 22`) — from the `id`
  field of `GET /engage/api/v1/timezone/list`
- IANA zoneId string (recommended for humans, e.g. `--timezone "Europe/London"`)
  — CLI looks it up in the list and resolves to the corresponding id

Invalid values (not in timezone-list) are rejected at `send --live` with
candidate examples in the error message.

CLI-managed fixed schedules are named by timezone slug
(`cli-anytime-<tz-slug>` / `cli-default-<tz-slug>`); different timezones do
not share the same schedule.

## Commands the agent runs vs. commands requiring confirmation

**Read-only (agent may run freely):**
- `init`, `doctor`, `doctor --check-api`
- `mailboxes`, `validate`
- `import` (local-only), `draft` (local-only)
- `status`, `list`, `list --remote`
- `outbox`, `outbox --view`
- `inbox`, `inbox --view`
- `ai-auto-reply show`
- `export`

**Requires explicit user "yes" per call:**
- `send --dry-run --yes`
- `send --live --yes` ← never auto-escalate
- `send --live --send-now` (extra confirm: "this bypasses the working-time window")
- `pause`, `resume`
- `reply --mail-id <ID>`
- `ai-auto-reply enable` (show prompt verbatim first)
- `ai-auto-reply disable`
- `reschedule`
- `inbox --mark-read`
- `steps remove` (mutates campaign structure)
- `delete --yes` (irreversible; list contents in chat first and re-confirm)

## Notes on backend semantics worth telling the user

- `sources="ai_mailer"` is auto-tagged by the CLI so `list --remote` only shows
  what the CLI created. The user's own web-created sequences are filtered out.
- After `send --live`, the campaign appears in the FlashRev web UI sequence
  list. Editing it there will not break the CLI, but the CLI re-commits go
  through a Full-Replace edit — show user the diff first if they've modified
  the sequence in the web UI.
- `--send-now` makes step 1 fire immediately (skips delay + working-time
  window + holiday calendar). Later steps follow their normal `--delay-days`.
- Prospect replies stop the sequence (default `prospectRepliesEnabled=1`).
  If `ai-auto-reply enable` is on, the LLM will first send an auto-reply,
  *then* the sequence stops further outgoing steps for that contact.

## Failure recovery

- `send --live` failed midway: re-run; the CLI's edit-path detects the
  existing `sequenceId` and merges; no duplicate emails.
- Unknown error from backend (`code: 400, msg: "Unknown error !"`): the
  backend swallowed the real error. Check `.flashrev/campaigns/<id>/campaign.json`
  → `steps[]` for missing fields (see `references/api_contract.md` for the
  full required-field list).
- `list` shows a campaign but `outbox/inbox` returns 0: the sequence was
  paused or deleted server-side. Run `status` to confirm.

For full request/response shapes, paths, and known field traps, see
[references/api_contract.md](references/api_contract.md).