--- 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 `** 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 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: `). - 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 --body "Thanks {{...}}" # (MAIL_ID is the first column of `inbox` output) # Mark as read without replying: flashrev-mailer inbox --mark-read # View full event timeline for a sent message: flashrev-mailer outbox --view ``` **`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-` / `cli-default-`); 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 ` - `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//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).