@letterstory/cli 0.45.0 → 0.47.0

package/README.md

@@ -386,6 +386,8 @@ letterstory admin crm accounts --stage demo_scheduled  # with likelihood
 letterstory admin crm score <account-id>               # recompute; prints the factors
 letterstory admin crm slack-channels [--all]           # Watchdog channels + the account each is linked to
 letterstory admin crm link-slack <account-id> C0123ABC # the CRM's watch-only Slack link (`none` unlinks)
+letterstory admin crm import leads.csv --dry-run       # bulk-import leads: what would be created/matched
+letterstory admin crm import leads.csv --tag "YC W26"  # …and for real (dedupes by domain, then company name)
 
 # One-click onboarding of a won client (key needs crm:write + fleet:onboard + org:create)
 letterstory admin crm onboard <account-id> --domain acme.com \
@@ -393,11 +395,16 @@ letterstory admin crm onboard <account-id> --domain acme.com \
   --slack jane@acme.com --invite jane@acme.com:admin --invite bob@acme.com
 letterstory admin crm onboarding <account-id>          # step-by-step progress (sites refreshed)
 letterstory admin crm retry-onboarding <onboarding-id> # re-run only the failed steps
+letterstory admin crm onboard-plan <account-id>        # what the calls say: sites, Slack/app people, paid?
+letterstory admin crm payment-link <account-id>        # Stripe Payment Link at the deal amount (billing:write)
 ```
 
 `onboard` runs org → link → phantom sites → Slack channel → checklist → app invites →
 stage in one call. Each site is a real (not test) fleet build; `--site ""` lets the engine
-infer its beat from the client's homepage.
+infer its beat from the client's homepage. `onboard-plan` reads the account's recorded calls
+(newest first, cached per set of calls; `--refresh` re-reads) and says how many sites, what each
+is about, who to invite, and whether they've paid. `payment-link` stamps the account's org on
+the Stripe subscription, so paying through it binds and marks the account paid by itself.
 
 Every trigger — Cal.com bookings, Circleback recordings, Letterhome dinner RSVPs, RB2B
 visits, and what an agent records here — goes through one intake (`ingestSignal`,
@@ -663,6 +670,50 @@ letterstory insights bank [--source phantoms|marketing|all] [--phantom <uuid>]..
 letterstory insights access [--period 14d|30d|90d] [--collection <uuid>]
 ```
 
+## Outbound email — mailers, sequences, prospects
+
+The cold-email stack: sending **mailers** (real Google mailboxes on domains we own), **sequences**
+(multi-step flows sent from them, with a review queue) and **prospects** (who you write to). Writes
+here can SEND email or spend money, so they refuse unknown flags instead of ignoring them. Scopes:
+`mailer:read` / `mailer:manage` / `mailer:provision`, `sequence:read` / `sequence:write`,
+`prospect:read` / `prospect:write` (the write scopes are admin-only keys).
+
+```bash
+# Mailers
+letterstory mailers list [--domain acme.com]                 # status + daily send limit
+letterstory mailers domain <owned-domain-id>                 # provisioning stage, DNS, mailers on it
+letterstory mailers messages <mailer-id> [--folder inbox|sent|all] [--limit 25]   # envelopes
+letterstory mailers message <mailer-id> <uid> --folder inbox # one message, plain-text body
+letterstory mailers forward <mailer-id> --to me@acme.com    # or --clear
+letterstory mailers warmup start|pause <mailer-id>           # 10 days to ready
+letterstory mailers limit <mailer-id> 40                     # 0..500; refused while warming
+letterstory mailers retire <mailer-id>                       # disable; history kept
+letterstory mailers retire <mailer-id> --release-mailbox --yes   # also delete the hosted mailbox (irreversible)
+letterstory mailers suppressions [list] [--reason bounce] [--limit 100]
+letterstory mailers suppressions add person@x.com --reason manual --note "asked to stop"
+letterstory mailers suppressions remove person@x.com         # only 'manual' entries; opt-outs stay
+
+# Launching buys a domain (up to $30) and the mailboxes, so it is a tool call, not a command:
+letterstory call launch_mailers --args '{"domain":"acme-mail.com","mailers":[{"local_part":"hello"}],"consent_attested":true,"mail_from_postal_address":"…"}'
+
+# Org-level mail settings
+letterstory mail connections                                 # connected mailboxes, key + postal address status
+letterstory mail postal-address "123 Main St, Portland, OR 97201"   # CAN-SPAM footer
+
+# Sequences (approving or enrolling SENDS)
+letterstory sequences list | get <id> | create | update <id> | pause <id> | resume <id>
+letterstory sequences enroll <id> --list <list-id>           # or --email a@x.com ...
+letterstory sequences review list | approve <item-id> | skip <item-id> | edit <item-id> --subject "…"
+letterstory sequences links create --days 2                  # no-login phone review link, shown once
+
+# Prospects
+letterstory prospects lists | ls --list <list-id> | get <id> | import --csv-file leads.csv --list-name "Q4"
+letterstory prospects source --description "heads of growth at seed-stage fintech" --list-name "Fintech"
+```
+
+Connecting a bring-your-own Gmail mailbox needs a browser (Google consent), so it is done in the
+app; `letterstory mail connections` shows what is connected.
+
 ## Anything else
 
 Every Letterstory tool is reachable, not just the ones with a dedicated command group:

package/lib/cli.mjs

@@ -45,6 +45,7 @@ import {
 	cmdSequences,
 	cmdProspects,
 	cmdMail,
+	cmdMailers,
 	cmdAdmin,
 	cmdFeedback,
 	cmdOfferings,
@@ -52,7 +53,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.45.0";
+export const VERSION = "0.47.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -62,6 +63,7 @@ const BOOLEAN_FLAGS = new Set([
 	"confirm-missing-target",
 	"no-wait",
 	"no-checklist",
+	"refresh",
 	"accept",
 	"help",
 	"version",
@@ -557,7 +559,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        session (a trial per arm), linked to its
                                                        ledger entry. Written by \`npm run lab --
                                                        publish\` in the kernels repo.
-  admin crm signals [--status new] [--intent qualified] [--source rb2b] [--account <id>]
+  admin crm import <file.csv> [--source <name>] [--tag "…"] [--dry-run]
+          | signals [--status new] [--intent qualified] [--source rb2b] [--account <id>]
           | record --title "…" [--source bookface] [--kind other] [--intent qualified]
                    [--name …] [--email …] [--company …] [--domain …] [--linkedin …] [--detail …]
           | signal <id> qualify|dismiss|link [--account <id>]
@@ -569,7 +572,10 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N]
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
           | onboarding <account-id> | retry-onboarding <onboarding-id>
-                                                       The staff CRM's pipeline: the inbound signal
+          | onboard-plan <account-id> [--refresh]
+          | payment-link <account-id> [--amount-cents N] [--description "…"]
+                                                       The staff CRM's pipeline: bulk-importing a
+                                                       CSV of leads, the inbound signal
                                                        feed, recording a signal with no webhook
                                                        (Bookface, a tweet like), qualifying or
                                                        dismissing one, and the explained score.
@@ -585,7 +591,9 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        only what failed.
                                                        Needs crm:read (reads) / crm:write (writes);
                                                        onboard + retry also need fleet:onboard and
-                                                       org:create.
+                                                       org:create. onboard-plan reads the calls
+                                                       (sites, who to invite, paid or not);
+                                                       payment-link needs billing:write.
   admin tuning-context [--q "<question>"]              The experiment agent's context pack (JSON):
                                                        the pipeline as deployed, levers, measures,
                                                        goals, related history.
@@ -791,6 +799,22 @@ Prospects (who you write to):
            [--first-name] [--last-name] [--title] [--company] [--website] [--linkedin] [--school]
            [--city] [--country] [--years] [--notes] [--custom key=value]...
 
+Mailers (the sending mailboxes; launching one buys a domain, so use: call launch_mailers):
+  mailers list [--domain <apex>]                       Your mailers + status + daily send limit
+  mailers domain <owned-domain-id>                     Provisioning stage, DNS state, mailers on a domain
+  mailers messages <mailer-id> [--folder all|inbox|sent] [--limit <n>]
+                                                       Recent mail (envelopes)
+  mailers message <mailer-id> <uid> --folder inbox|sent
+                                                       One message in full (plain-text body)
+  mailers forward <mailer-id> (--to <email> | --clear) Copy inbound mail to an address
+  mailers warmup start|pause <mailer-id>               Start / pause warming (10 days to ready)
+  mailers limit <mailer-id> <per-day>                  Daily send limit, 0..500 (not while warming)
+  mailers retire <mailer-id> [--release-mailbox --yes] Disable a mailer; --release-mailbox also deletes
+                                                       the hosted mailbox (stops billing, irreversible)
+  mailers suppressions [list] [--reason <r>] [--limit <n>]
+  mailers suppressions add <address> [--reason unsubscribe|bounce|complaint|manual] [--note <t>]
+  mailers suppressions remove <address>                Only 'manual' entries can be removed
+
 Mail:
   mail connections                                     Connected mailboxes, Google connect, Vercel key + mailing address status
   mail postal-address "<address>"                      Set the org's CAN-SPAM mailing address (email footers)
@@ -881,6 +905,7 @@ const CLIENT_COMMANDS = {
 	sequences: cmdSequences,
 	prospects: cmdProspects,
 	mail: cmdMail,
+	mailers: cmdMailers,
 	feedback: cmdFeedback,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,

package/lib/commands/admin.mjs

@@ -7,7 +7,7 @@
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
-//   admin crm signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding …  (crm:read / crm:write)
+//   admin crm import|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -425,11 +425,135 @@ function accountLine(a) {
 	return `${a.id}  [${a.stage}]  ${score}  ${a.name}${a.domain ? ` (${a.domain})` : ""}${a.isYc ? " · YC" : ""}`;
 }
 
+/* ------------------------------------------------------ CRM lead import (CSV) */
+
+/** RFC 4180-ish: quoted fields, doubled quotes, CRLF/LF, a BOM. Returns rows of cells. */
+export function parseCsvText(text) {
+	const src = text.replace(/^/, "");
+	const rows = [];
+	let row = [];
+	let cell = "";
+	let quoted = false;
+	for (let i = 0; i < src.length; i++) {
+		const c = src[i];
+		if (quoted) {
+			if (c === '"') {
+				if (src[i + 1] === '"') {
+					cell += '"';
+					i++;
+				} else quoted = false;
+			} else cell += c;
+		} else if (c === '"') quoted = true;
+		else if (c === ",") {
+			row.push(cell);
+			cell = "";
+		} else if (c === "\n" || c === "\r") {
+			if (c === "\r" && src[i + 1] === "\n") i++;
+			row.push(cell);
+			rows.push(row);
+			row = [];
+			cell = "";
+		} else cell += c;
+	}
+	if (cell !== "" || row.length > 0) {
+		row.push(cell);
+		rows.push(row);
+	}
+	return rows.filter((r) => r.some((c) => c.trim() !== ""));
+}
+
+/** Spreadsheet header → CrmImportRow field (headers compared lower-cased, letters and digits only). */
+const CRM_IMPORT_HEADERS = {
+	company: ["company", "companyname", "organization", "organisation", "account", "accountname"],
+	domain: ["domain", "companydomain"],
+	website: ["website", "url", "companywebsite", "companyurl", "site"],
+	name: ["name", "fullname", "contact", "contactname", "person"],
+	firstName: ["firstname", "first", "givenname"],
+	lastName: ["lastname", "last", "surname", "familyname"],
+	email: ["email", "emailaddress", "workemail", "businessemail"],
+	title: ["title", "jobtitle", "position", "role"],
+	linkedin: ["linkedin", "linkedinurl", "linkedinprofile"],
+	phone: ["phone", "phonenumber", "mobile"],
+	notes: ["notes", "note", "comments", "description"],
+	yc: ["yc", "isyc", "ycombinator"],
+	batch: ["batch", "ycbatch"],
+};
+
+/** A CSV's text → the CrmImportRow[] the import route takes (unknown columns are ignored). */
+export function csvToImportRows(text) {
+	const [header, ...body] = parseCsvText(text);
+	if (!header) return { rows: [], mapped: [] };
+	const key = (h) => h.toLowerCase().replace(/[^a-z0-9]/g, "");
+	const columns = header.map((h) => {
+		const k = key(h);
+		return Object.keys(CRM_IMPORT_HEADERS).find((f) => CRM_IMPORT_HEADERS[f].includes(k)) ?? null;
+	});
+	const rows = body.map((cells) => {
+		const row = {};
+		columns.forEach((field, i) => {
+			const v = (cells[i] ?? "").trim();
+			if (field && v && row[field] === undefined) row[field] = v;
+		});
+		return row;
+	});
+	return { rows, mapped: [...new Set(columns.filter(Boolean))] };
+}
+
+/** The route's cap (CRM_IMPORT_MAX_ROWS in src/types/crm.ts). */
+const CRM_IMPORT_CHUNK = 2000;
+
+/**
+ * `admin crm import <file.csv> [--source name] [--tag "…"] [--dry-run]` — the same importLeads
+ * the CRM's upload calls (POST /api/superadmin/crm/import), 2,000 rows per request.
+ */
+async function cmdAdminCrmImport(ctx, path) {
+	const { flags, io } = ctx;
+	if (!path) throw new CliError('Usage: admin crm import <file.csv> [--source name] [--tag "…"] [--dry-run]');
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (err) {
+		throw new CliError(`Could not read ${path}: ${err.message}`);
+	}
+	const { rows, mapped } = csvToImportRows(text);
+	if (rows.length === 0) throw new CliError(`${path} has no data rows`);
+	if (!["company", "domain", "website", "email"].some((f) => mapped.includes(f))) {
+		throw new CliError("No company, domain, website or email column found in the header row");
+	}
+	const source = flagStr(flags.source) ?? path.split(/[\\/]/).pop();
+	const dryRun = flagBool(flags["dry-run"]);
+	const total = { created: 0, matched: 0, contactsAdded: 0, skipped: 0, rows: [] };
+	for (let offset = 0; offset < rows.length; offset += CRM_IMPORT_CHUNK) {
+		const r = await staffPost(
+			ctx,
+			`${CRM}/import`,
+			compact({ rows: rows.slice(offset, offset + CRM_IMPORT_CHUNK), source, dryRun, tag: flagStr(flags.tag) })
+		);
+		total.created += r.created;
+		total.matched += r.matched;
+		total.contactsAdded += r.contactsAdded;
+		total.skipped += r.skipped;
+		total.rows.push(...r.rows.map((x) => ({ ...x, index: x.index + offset })));
+	}
+	if (flagBool(flags.json)) return printResult(io, flags, total);
+	const errors = total.rows.filter((x) => x.status === "error").length;
+	io.log(
+		`${dryRun ? "Dry run — would import" : "Imported"} ${rows.length} rows from ${source} (columns: ${mapped.join(", ")}):\n` +
+			`  ${total.created} accounts ${dryRun ? "to create" : "created"}, ${total.matched} matched, ` +
+			`${total.contactsAdded} contacts ${dryRun ? "to add" : "added"}, ${total.skipped} skipped${errors ? `, ${errors} errors` : ""}`
+	);
+	for (const x of total.rows.filter((y) => y.status === "skipped" || y.status === "error")) {
+		// +2: the header is line 1 and the index is 0-based.
+		io.log(`  line ${x.index + 2}: ${x.status} — ${x.reason ?? ""}`);
+	}
+}
+
 function onboardingLines(o) {
 	if (!o) return "(never onboarded from the CRM)";
 	const mark = { done: "✓", skipped: "–", failed: "✗", running: "…", pending: "·" };
 	return [
 		`${o.id}  started ${o.startedAt.slice(0, 16).replace("T", " ")}${o.finishedAt ? "  finished" : "  in progress"}`,
+		...(o.billing ? [`  ${billingLine(o.billing)}`] : []),
 		...o.steps.map(
 			(s) =>
 				`  ${mark[s.status] ?? "?"} ${s.key.padEnd(9)} ${s.status}${s.progress ? ` (${s.progress.done}/${s.progress.total})` : ""}${s.detail ? `  ${s.detail}` : ""}${s.error ? `\n      error: ${s.error}` : ""}`
@@ -437,6 +561,32 @@ function onboardingLines(o) {
 	].join("\n");
 }
 
+function dollars(cents) {
+	return `$${(cents / 100).toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+}
+
+function billingLine(b) {
+	const paid = b.paid
+		? `PAID${b.mrrCents ? ` (${dollars(b.mrrCents)}/mo)` : ""}${b.paidAt ? ` since ${b.paidAt.slice(0, 10)}` : ""}`
+		: "NOT PAID";
+	return `billing: ${paid}${b.paymentLinkUrl ? `  link: ${b.paymentLinkUrl}` : ""}`;
+}
+
+function planLines(p) {
+	return [
+		`domain: ${p.domain ?? "(unknown)"}`,
+		`sites: ${p.sites.length}`,
+		...p.sites.map(
+			(s, i) => `  ${i + 1}. ${s.direction || "(infer from their homepage)"}${s.why ? `  — ${s.why}` : ""}`
+		),
+		`slack: ${p.slackEmails.join(", ") || "(nobody found)"}`,
+		`invites: ${p.invites.map((i) => `${i.email}:${i.role}`).join(", ") || "(none)"}`,
+		...(p.notes ? [`notes: ${p.notes}`] : []),
+		billingLine(p.billing),
+		`read: ${p.sources.map((s) => `${s.title ?? s.transcriptId} (${s.occurredAt.slice(0, 10)})`).join("; ") || "(no calls on file)"}`,
+	].join("\n");
+}
+
 /**
  * `admin crm onboard` body from flags — the same CrmOnboardBodySchema the desk sends.
  * --site "<direction>" per site (repeatable; "" = infer from the homepage) and/or
@@ -488,6 +638,8 @@ async function cmdAdminCrm(ctx) {
 	const json = flagBool(flags.json);
 	const out = (result, line) => (json ? printResult(io, flags, result) : io.log(line(result)));
 	switch (sub) {
+		case "import":
+			return cmdAdminCrmImport(ctx, id);
 		case "signals": {
 			const params = new URLSearchParams(
 				compact({
@@ -688,6 +840,32 @@ async function cmdAdminCrm(ctx) {
 				onboardingLines(x.onboarding)
 			);
 		}
+		case "onboard-plan": {
+			// admin crm onboard-plan <account-id> [--refresh] — what the calls say onboarding
+			// should set up (sites, Slack/app people, notes) + paid or not. --refresh re-reads.
+			if (!id) throw new CliError("Usage: admin crm onboard-plan <account-id> [--refresh]");
+			const q = flagBool(flags.refresh) ? "?refresh=1" : "";
+			return out(await staffRequest(ctx, "GET", `${CRM}/accounts/${id}/onboard/plan${q}`), (x) =>
+				planLines(x.plan)
+			);
+		}
+		case "payment-link": {
+			// admin crm payment-link <account-id> [--amount-cents N] [--description "…"] — a Stripe
+			// Payment Link for the monthly subscription (default: the deal amount). The key needs
+			// crm:write + billing:write.
+			if (!id)
+				throw new CliError('Usage: admin crm payment-link <account-id> [--amount-cents N] [--description "…"]');
+			const r = await staffPost(
+				ctx,
+				`${CRM}/accounts/${id}/payment-link`,
+				compact({ amountCents: flagNum(flags["amount-cents"]), description: flagStr(flags.description) })
+			);
+			return out(
+				r,
+				(x) =>
+					`${x.url}  (${dollars(x.amountCents)}/month${x.orgId ? "" : " — no org yet: bind in Fleet → Billing"})`
+			);
+		}
 		case "retry-onboarding": {
 			// admin crm retry-onboarding <onboarding-id> — re-run the failed/pending steps.
 			if (!id) throw new CliError("Usage: admin crm retry-onboarding <onboarding-id>");
@@ -696,7 +874,7 @@ async function cmdAdminCrm(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin crm signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding … (see --help)"
+				"Usage: admin crm import|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
 			);
 	}
 }

package/lib/commands/outbound.mjs

@@ -1,4 +1,4 @@
-// `sequences`, `prospects` and `mail` — the outbound email stack, as thin wrappers
+// `sequences`, `prospects`, `mailers` and `mail` — the outbound email stack, as thin wrappers
 // over the MCP tools, which call the same lib functions the app's /api/sequences
 // and /api/prospects routes do. Every call is built from the ARGS map below, so
 // `scripts/parity-check.ts` can hold each command to its tool's input schema.
@@ -58,6 +58,22 @@ const mailerIds = {
 	},
 };
 
+// A required positional that must be a whole number (the server schema wants a number, not a string).
+function intPositional(index, label) {
+	return {
+		value: (_flags, positionals) => {
+			const raw = positionals[index];
+			if (raw === undefined) throw new CliError(`Missing required <${label}>`);
+			const n = Number(raw);
+			if (!Number.isInteger(n)) throw new CliError(`<${label}> must be a whole number (got ${raw})`);
+			return n;
+		},
+	};
+}
+
+const SUPPRESSION_REASONS = ["unsubscribe", "bounce", "complaint", "manual"];
+const MAILER_FOLDERS = ["inbox", "sent"];
+
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 export const ARGS = {
 	list_sequences: {},
@@ -112,6 +128,9 @@ export const ARGS = {
 	get_prospect_list: {
 		list_id: { positional: 0, label: "list-id", required: true },
 	},
+	delete_prospect_list: {
+		list_id: { positional: 0, label: "list-id", required: true },
+	},
 	list_prospects: {
 		list_id: "list",
 		status: { flag: "status", enum: PROSPECT_STATUSES },
@@ -166,6 +185,59 @@ export const ARGS = {
 		notes: "notes",
 		custom: { value: readCustom },
 	},
+	list_mailers: {
+		domain: "domain",
+	},
+	get_mailer_domain_status: {
+		owned_domain_id: { positional: 0, label: "owned-domain-id", required: true },
+	},
+	list_mailer_messages: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+		folder: { flag: "folder", enum: ["all", ...MAILER_FOLDERS] },
+		limit: { flag: "limit", type: "num" },
+	},
+	get_mailer_message: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+		uid: intPositional(1, "uid"),
+		folder: { flag: "folder", required: true, enum: MAILER_FOLDERS },
+	},
+	set_mailer_forwarding: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+		forward_to: {
+			value: (flags) => {
+				if (flags.clear === true) return null;
+				const to = flagStr(flags.to);
+				if (to === undefined) throw new CliError("Pass --to <email> (or --clear to stop forwarding)");
+				return to;
+			},
+		},
+	},
+	start_mailer_warmup: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+	},
+	pause_mailer_warmup: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+	},
+	set_mailer_daily_send_limit: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+		daily_send_limit: intPositional(1, "per-day"),
+	},
+	retire_mailer: {
+		mailer_id: { positional: 0, label: "mailer-id", required: true },
+		release_mailbox: { flag: "release-mailbox", type: "bool" },
+	},
+	add_email_suppression: {
+		address: { positional: 0, label: "address", required: true },
+		reason: { flag: "reason", enum: SUPPRESSION_REASONS },
+		note: "note",
+	},
+	list_email_suppressions: {
+		reason: { flag: "reason", enum: SUPPRESSION_REASONS },
+		limit: { flag: "limit", type: "num" },
+	},
+	remove_email_suppression: {
+		address: { positional: 0, label: "address", required: true },
+	},
 	get_mail_connections: {},
 	set_mail_postal_address: {
 		mail_postal_address: { positional: 0, label: "address", required: true },
@@ -180,6 +252,7 @@ const VALUE_FLAGS = {
 	update_review_item: ["body", "file"],
 	import_prospects_csv: ["csv", "csv-file"],
 	update_prospect: ["custom"],
+	set_mailer_forwarding: ["to", "clear"],
 };
 
 async function run(ctx, tool, message) {
@@ -280,7 +353,7 @@ async function sequencesLinks(ctx, sub) {
 	}
 }
 
-const PROSPECTS_USAGE = `Usage: prospects <lists|list|ls|get|create-list|import|source|enrich|update>`;
+const PROSPECTS_USAGE = `Usage: prospects <lists|list|ls|get|create-list|delete-list|import|source|enrich|update>`;
 
 export async function cmdProspects(ctx) {
 	const sub = ctx.positionals[0];
@@ -297,6 +370,8 @@ export async function cmdProspects(ctx) {
 			return run(rest, "get_prospect");
 		case "create-list":
 			return run(rest, "create_prospect_list", "List ready.");
+		case "delete-list":
+			return run(rest, "delete_prospect_list", "List deleted (its prospects stay).");
 		case "import":
 			return run(rest, "import_prospects_csv", "Imported.");
 		case "source":
@@ -314,6 +389,66 @@ export async function cmdProspects(ctx) {
 	}
 }
 
+const MAILERS_USAGE = `Usage: mailers <list|domain|messages|message|forward|warmup|limit|retire|suppressions>`;
+
+export async function cmdMailers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return run(rest, "list_mailers");
+		case "domain":
+			return run(rest, "get_mailer_domain_status");
+		case "messages":
+			return run(rest, "list_mailer_messages");
+		case "message":
+		case "show":
+			return run(rest, "get_mailer_message");
+		case "forward":
+			return run(rest, "set_mailer_forwarding", "Forwarding updated.");
+		case "warmup": {
+			const action = rest.positionals[0];
+			const inner = { ...rest, positionals: rest.positionals.slice(1) };
+			if (action === "start") return run(inner, "start_mailer_warmup", "Warmup started.");
+			if (action === "pause") return run(inner, "pause_mailer_warmup", "Warmup paused.");
+			throw new CliError(`Unknown warmup action: ${action ?? "(none)"}. Try: start, pause`);
+		}
+		case "limit":
+			return run(rest, "set_mailer_daily_send_limit", "Daily send limit set.");
+		case "retire": {
+			if (rest.flags["release-mailbox"] && !rest.flags.yes) {
+				const id = flagStr(rest.positionals[0]) ?? "<mailer-id>";
+				ctx.io.error(
+					`--release-mailbox deletes the hosted mailbox at the provider and cannot be undone. Re-run with --yes to confirm: ${ctx.bin} mailers retire ${id} --release-mailbox --yes`
+				);
+				return 1;
+			}
+			return run(rest, "retire_mailer", "Mailer retired: nothing further sends from it.");
+		}
+		case "suppressions":
+			return mailersSuppressions(rest, rest.positionals[0]);
+		default:
+			throw new CliError(`Unknown mailers subcommand: ${sub ?? "(none)"}. ${MAILERS_USAGE}`);
+	}
+}
+
+async function mailersSuppressions(ctx, sub) {
+	const inner = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+		case undefined:
+			return run(sub === undefined ? ctx : inner, "list_email_suppressions");
+		case "add":
+			return run(inner, "add_email_suppression", "Added to the do-not-send list.");
+		case "remove":
+			return run(inner, "remove_email_suppression", "Removed from the do-not-send list.");
+		default:
+			throw new CliError(`Unknown suppressions subcommand: ${sub}. Try: list, add, remove`);
+	}
+}
+
 export async function cmdMail(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.45.0",
+	"version": "0.47.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",