@letterstory/cli 0.46.0 → 0.47.0

package/README.md

@@ -670,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.46.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.
@@ -798,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)
@@ -888,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/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.46.0",
+	"version": "0.47.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",