argorant 0.13.0 → 0.14.1

package/README.md

@@ -252,10 +252,12 @@ npx argorant webhooks rm 3 --yes
 ```
 
 `credits buy` shows the quote first and only buys after a yes: at a terminal it asks, anywhere
-else it needs `--yes`. When your workspace saved its card for API and agent purchases and the
-purchase fits the limits you set in Settings, that card is charged right away. Otherwise you get a
-payment link to pay yourself, and the credits are added once the payment goes through.
-`--pay-with link` always gives the link. Bought credits stay valid for 365 days.
+else it needs `--yes`. An agent that runs the CLI for someone passes that person's own words with
+`--confirmation "yes, buy 5,000 credits"`; every purchase records how it was confirmed. When the
+account owner allowed purchases with the saved card in Settings > Billing (up to a monthly limit)
+and the purchase fits, that card is charged right away. Otherwise you get a payment link to pay
+yourself, and the credits are added once the payment goes through. `--pay-with link` always gives
+the link. Bought credits stay valid for 365 days.
 
 `lists rm` and `webhooks rm` work the same way: they ask at a terminal and need `--yes` anywhere
 else. A webhook's signing secret is shown once, when you add it.
@@ -282,6 +284,10 @@ argorant campaigns create --name "Q4 CFO outreach" [--daily-limit 40] [--timezon
 argorant campaigns emails set <campaign> --step 1 --subject "Quick question, {{first_name}}" --body-file ./step1.txt
 argorant campaigns emails set <campaign> --step 2 --body "Bumping this." --delay-days 3
 argorant campaigns emails set <campaign> --file emails.json        # whole sequence at once
+argorant campaigns subsequences list <campaign>                   # reply-keyword follow-ups
+argorant campaigns subsequences set <campaign> --file subsequences.json   # up to 5, replaces the set
+#   keywords also match in capitals, as a plural, with a small typo or inside a short sentence;
+#   "not interested" and replies that ask to stop never start a subsequence
 argorant campaigns leads add <campaign> --list <list-id>           # a saved list
 argorant campaigns leads add <campaign> --csv leads.csv            # email, first_name, last_name, company, title
 argorant campaigns senders set <campaign> --emails a@x.com,b@y.com # or --all
@@ -302,6 +308,40 @@ argorant inboxes connect-google --admin admin@yourdomain.com       # lists mailb
 argorant inboxes connect-google --admin admin@yourdomain.com --emails a@x.com,b@x.com   # or --all
 ```
 
+### Mailboxes from any email provider (SMTP and IMAP)
+
+Zoho, Fastmail, Yahoo, iCloud, IONOS, your web host or any other provider connect with their server settings.
+Argorant signs in twice before it saves anything: once to send (SMTP) and once to read replies (IMAP). A mailbox
+connects only when both work. The password is stored safely and never shown again; many providers need an app
+password instead of the normal one. Google and Microsoft mailboxes connect with their own sign-in instead.
+
+```
+argorant inboxes presets                                           # provider keys for --preset
+argorant inboxes test-smtp --email anna@acme.com --preset zoho     # checks sending and reading replies, saves nothing
+argorant inboxes connect-smtp --email anna@acme.com --preset zoho --name "Anna Weber"
+argorant inboxes connect-smtp --email anna@acme.com --smtp-host mail.acme.com --smtp-port 587 --imap-host mail.acme.com
+argorant inboxes connect-smtp --csv mailboxes.csv                  # many at once, a result per row
+```
+
+The password is never taken on the command line. Put it in an environment variable and name it with
+`--password-env NAME`, set `ARGORANT_MAILBOX_PASSWORD`, or type it when asked. `--imap-password-env NAME` sets a
+different password for reading replies. Connecting the same address again replaces its settings, which is how a
+mailbox is reconnected after a password change.
+
+CSV columns: `email, sender_name, preset, smtp_host, smtp_port, smtp_security, smtp_username, smtp_password,
+imap_host, imap_port, imap_security, imap_username, imap_password, daily_limit`. Each row needs `email`,
+`smtp_password` (or `password`) and either `preset` or `smtp_host` + `smtp_port` + `imap_host`. Empty columns take
+the defaults: the username is the email address, reading replies uses the sending sign-in, port 993, 25 emails a
+day. Security is `ssl`, `starttls` or `none`. Use port 587 for sending; if you give 465, Argorant tries 587 and
+saves 587 when it works. Rows go up 25 at a time; the command exits 1 when any row did not
+connect.
+
+```
+email,sender_name,preset,smtp_password
+anna@acme.com,Anna Weber,zoho,app-password-1
+ben@acme.com,Ben Hill,zoho,app-password-2
+```
+
 New mailboxes on their own new domains, ordered from the terminal. The quote shows every domain with its
 first-year and renewal price, the mailboxes, the total and how it is paid. When your workspace saved its card
 for API and agent purchases (you ticked that box when you paid an earlier order, and the setting in

package/bin/argorant.js

@@ -1460,6 +1460,89 @@ async function campaignsEmails(argv) {
   console.log(green("✓") + ` Saved ${(r.emails || emails).length} email(s) for ${dim(campaignId)}`);
 }
 
+// subsequences: follow-ups a reply keyword starts (GET / POST /api/v1/campaigns/{id}/subsequences).
+// The server replaces the whole set: subsequences left out are deleted with anyone still in them,
+// so `set` asks before it drops one that still has people in progress (-y skips the question).
+const SUBSEQUENCES_USAGE =
+  "usage: argorant campaigns subsequences list <campaign>\n" +
+  "   or: argorant campaigns subsequences set <campaign> --file subsequences.json [-y]\n" +
+  "   or: argorant campaigns subsequences clear <campaign> [-y]\n" +
+  '  subsequences.json: [{"name":"Interested","keywords":["interested","yes"],"emails":[{"body":"...","delay_days":0},{"body":"...","delay_days":3}]}]\n' +
+  "  Up to 5 subsequences, 1 to 10 keywords and 1 to 8 emails each. Email 1 defaults to the subject 'Re: {{thread_subject}}'.\n" +
+  "  Keywords also count in capitals, as a plural, with a small typo or inside a short sentence.\n" +
+  "  'not interested' and replies that ask to stop never start one.";
+
+function readSubsequencesFile(text, source) {
+  let data;
+  try { data = JSON.parse(text); } catch (e) { die(`${source}: not valid JSON (${e.message})`); }
+  const items = Array.isArray(data) ? data : data && Array.isArray(data.subsequences) ? data.subsequences : null;
+  if (!items) die(`${source}: expected a list of subsequences (or {"subsequences": [...]})`);
+  if (items.length > 5) die(`${source}: a campaign can have up to 5 subsequences (got ${items.length})`);
+  return items.map((item, i) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) die(`${source}: subsequence ${i + 1} is not an object`);
+    const keywords = typeof item.keywords === "string" ? item.keywords.split(",") : item.keywords;
+    if (!Array.isArray(keywords) || !keywords.some((k) => String(k || "").trim())) die(`${source}: subsequence ${i + 1} needs at least one keyword`);
+    const emails = item.emails || item.steps;
+    if (!Array.isArray(emails) || !emails.length) die(`${source}: subsequence ${i + 1} needs at least one email`);
+    const out = { name: item.name, keywords: keywords.map((k) => String(k).trim()).filter(Boolean), emails };
+    if (item.id) out.id = item.id;
+    return out;
+  });
+}
+
+function printSubsequences(r) {
+  const subs = r.subsequences || [];
+  console.log(dim(`Stop on reply: ${r.stop_on_reply === false ? "off" : "on"}`));
+  if (!subs.length) return console.log(dim("No subsequences. Add them with `argorant campaigns subsequences set <campaign> --file subsequences.json`."));
+  subs.forEach((s, i) => {
+    const st = s.stats || {};
+    console.log(`${bold(`${i + 1}. ${s.name}`)}  ${dim(s.id || "")}  ${s.status || ""}`);
+    console.log(`   keywords: ${(s.keywords || []).join(", ")}`);
+    console.log(`   emails: ${(s.steps || []).length}  ${dim(`in progress ${st.in_progress || 0}  replied ${st.replied || 0}  finished ${st.finished || 0}  sent ${st.emails_sent || 0}`)}`);
+    for (const step of s.steps || []) {
+      const preview = String(step.body || "").replace(/\s+/g, " ").slice(0, 70);
+      console.log(dim(`     ${step.step_number}. +${step.delay_days || 0}d  ${step.subject || "(same thread)"}  ${preview}`));
+    }
+  });
+}
+
+async function campaignsSubsequences(argv) {
+  const sub = argv[0];
+  if (!["list", "get", "set", "clear"].includes(sub)) die(SUBSEQUENCES_USAGE);
+  const key = requireKey();
+  const args = readFlags(argv.slice(1), { "--file": "file" });
+  const identifier = args._[0];
+  if (!identifier) die(SUBSEQUENCES_USAGE);
+  const campaignId = await resolveCampaign(args.base, key, identifier);
+  const route = `/api/v1/campaigns/${campaignId}/subsequences`;
+  if (sub === "list" || sub === "get") {
+    const r = need(await request("GET", args.base, route, { key }), "campaigns subsequences");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    return printSubsequences(r);
+  }
+  let items = [];
+  if (sub === "set") {
+    if (!args.file) die(SUBSEQUENCES_USAGE);
+    const text = args.file === "-" ? await readStdin() : (() => { try { return fs.readFileSync(args.file, "utf8"); } catch { die(`cannot read file: ${args.file}`); } })();
+    items = readSubsequencesFile(text, args.file === "-" ? "stdin" : args.file);
+  }
+  // What the replace would drop, and who is still inside it.
+  const current = need(await request("GET", args.base, route, { key }), "campaigns subsequences");
+  const keptIds = new Set(items.map((i) => i.id).filter(Boolean));
+  const dropped = (current.subsequences || []).filter((s) => !keptIds.has(s.id));
+  const busy = dropped.filter((s) => ((s.stats || {}).in_progress || 0) > 0);
+  if (dropped.length && !args.yes) {
+    const who = busy.length ? ` (${busy.map((s) => `${s.name}: ${s.stats.in_progress} in progress`).join(", ")})` : "";
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ok = await new Promise((r) => rl.question(`This removes ${dropped.length} subsequence(s)${who}, with anyone still in them. Continue? [y/N] `, (a) => { rl.close(); r(/^y/i.test(a)); }));
+    if (!ok) return console.log(dim("aborted"));
+  }
+  const r = need(await request("POST", args.base, route, { key, body: { subsequences: items } }), "campaigns subsequences set");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  console.log(green("✓") + ` Saved ${(r.subsequences || []).length} subsequence(s) for ${dim(campaignId)}`);
+  printSubsequences(r);
+}
+
 // senders: which connected mailboxes send this campaign.
 async function campaignsSenders(argv) {
   const sub = argv[0];
@@ -1912,6 +1995,9 @@ ${bold("USAGE")}
                 --gap 60-120 --unsubscribe|--no-unsubscribe --start YYYY-MM-DD --tags a,b --name "<n>"
   ${p} emails set <campaign> --file emails.json
   ${p} emails set <campaign> --step <n> --subject "..." (--body-file <path> | --body <text|->) [--delay-days <d>]
+  ${p} subsequences list <campaign>
+  ${p} subsequences set <campaign> --file subsequences.json [-y]   ${dim("reply keywords start follow-ups in the same thread")}
+  ${p} subsequences clear <campaign> [-y]
   ${p} leads add <campaign> --list <list-id> | --csv <file> [--include-catch-all]
   ${p} leads list <campaign> [--status replied] [--q text] [-n 50]
   ${p} leads remove <campaign> <email>
@@ -1929,6 +2015,10 @@ ${bold("USAGE")}
   ${bold("argorant inboxes")} set <mailbox> [--daily-limit 40] [--warmup|--no-warmup] [--active|--inactive] [--timezone <tz>]
   ${bold("argorant inboxes")} disconnect <mailbox>
   ${bold("argorant inboxes")} connect-google --admin <admin@yourdomain.com> [--emails a,b | --all]
+  ${bold("argorant inboxes")} connect-smtp --email <address> --preset <key> [--name "Sender"] [--password-env NAME]   ${dim("any provider; --smtp-host/--imap-host without a preset")}
+  ${bold("argorant inboxes")} connect-smtp --csv mailboxes.csv   ${dim("many at once, 25 per request, a result per row")}
+  ${bold("argorant inboxes")} test-smtp --email <address> --preset <key>   ${dim("checks sending and reading replies, saves nothing")}
+  ${bold("argorant inboxes")} presets   ${dim("provider keys for --preset (zoho, fastmail, yahoo, icloud, ...)")}
   ${bold("argorant inboxes")} endings   ${dim("the domain endings on offer (com, net, org, co, sbs, biz, info)")}
   ${bold("argorant inboxes")} suggest <website|brand> [--ending com] [-n 20]   ${dim("free domain names with prices")}
   ${bold("argorant inboxes")} quote --mailboxes 100 [--company acme.com] [--domains a.com,b.com] [--currency usd|eur] [--billing month|quarter]
@@ -1976,6 +2066,8 @@ async function cmdCampaigns(argv) {
     replies: campaignsReplies,
     analytics: campaignsAnalytics,
     emails: campaignsEmails,
+    subsequences: campaignsSubsequences,
+    subsequence: campaignsSubsequences,
     steps: campaignsSteps,
     senders: campaignsSenders,
     inboxes: campaignsInboxes,
@@ -2000,7 +2092,7 @@ async function cmdInboxes(argv) {
     const r = await fetchPages(args.base, key, "/api/v1/inboxes", { limit: 100 }, "inboxes", "inboxes list", true);
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     const rows = r.inboxes || [];
-    if (!rows.length) return console.log(dim("No mailboxes connected yet. Connect Google Workspace with `argorant inboxes connect-google --admin ...` or Microsoft 365 in the app."));
+    if (!rows.length) return console.log(dim("No mailboxes connected yet. Connect Google Workspace with `argorant inboxes connect-google --admin ...`, any other provider with `argorant inboxes connect-smtp --email ... --preset ...`, or Microsoft 365 in the app."));
     for (const i of rows) {
       console.log(`${bold(i.email)}  ${dim(i.name || "")}`);
       console.log(dim(`  ${i.provider} · ${i.status}${i.health ? ` · ${i.health}` : ""} · today ${i.sent_today || 0}/${i.daily_limit || "?"}`));
@@ -2207,7 +2299,267 @@ async function cmdInboxes(argv) {
     if (args.json) return console.log(JSON.stringify(r, null, 2));
     return console.log(green("✓") + ` Bundle ${target} cancelled${r.existing ? dim(" (already)") : ""}`);
   }
-  die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, endings, suggest, quote, order, status, renewal, cancel-bundle)`);
+  if (sub === "presets") {
+    const args = readFlags(argv.slice(1));
+    const r = need(await request("GET", args.base, "/api/v1/inboxes/smtp/presets", { key }), "inboxes presets");
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    for (const p of r.presets || []) {
+      const out = p.smtp_host ? `${p.smtp_host}:${p.smtp_port} ${p.smtp_secure}` : "you enter the servers";
+      const inn = p.imap_host ? `${p.imap_host}:${p.imap_port} ${p.imap_secure}` : "";
+      console.log(`${bold(p.key.padEnd(14))} ${p.label}`);
+      console.log(dim(`  sending ${out}${inn ? `  ·  reading replies ${inn}` : ""}`));
+      if (p.hint) console.log(dim(`  ${p.hint}`));
+    }
+    return;
+  }
+  if (sub === "test-smtp" || sub === "connect-smtp") return cmdSmtpMailbox(sub, argv.slice(1), key);
+  die(`unknown inboxes subcommand: ${sub} (list, set, disconnect, connect-google, connect-smtp, test-smtp, presets, endings, suggest, quote, order, status, renewal, cancel-bundle)`);
+}
+
+// ---- mailboxes from any email provider (SMTP sending + IMAP replies), 0.14.0 ----
+// The password is never taken on the command line (shell history): --password-env NAME, the
+// ARGORANT_MAILBOX_PASSWORD variable, a hidden prompt, or the CSV file for many mailboxes.
+const SMTP_FLAGS = {
+  "--email": "email", "--name": "name", "--preset": "preset",
+  "--smtp-host": "smtpHost", "--smtp-port": "smtpPort", "--smtp-security": "smtpSecurity", "--smtp-user": "smtpUser",
+  "--imap-host": "imapHost", "--imap-port": "imapPort", "--imap-security": "imapSecurity", "--imap-user": "imapUser",
+  "--daily-limit": "dailyLimit", "--password-env": "passwordEnv", "--imap-password-env": "imapPasswordEnv", "--csv": "csv",
+};
+const SMTP_BULK_CHUNK = 25;
+const SMTP_USAGE = `usage: argorant inboxes connect-smtp --email <address> (--preset <key> | --smtp-host <h> --smtp-port <p> --imap-host <h>)
+         [--name "Sender Name"] [--smtp-security starttls|ssl|none] [--smtp-user <u>] [--imap-port 993]
+         [--imap-security ssl|starttls|none] [--imap-user <u>] [--daily-limit 25] [--password-env NAME] [--imap-password-env NAME]
+       argorant inboxes connect-smtp --csv mailboxes.csv
+       argorant inboxes test-smtp   (same flags as connect-smtp for one mailbox; saves nothing)
+       argorant inboxes presets     (the provider keys for --preset)`;
+// CSV header -> field (lower case, spaces and dashes as underscores).
+const SMTP_CSV_COLUMNS = {
+  email: "email", sender_name: "sender_name", name: "sender_name", display_name: "sender_name", preset: "preset",
+  smtp_host: "smtp_host", smtp_port: "smtp_port", smtp_security: "smtp_security", smtp_secure: "smtp_security",
+  smtp_username: "smtp_username", smtp_user: "smtp_username", smtp_password: "smtp_password", password: "smtp_password",
+  imap_host: "imap_host", imap_port: "imap_port", imap_security: "imap_security", imap_secure: "imap_security",
+  imap_username: "imap_username", imap_user: "imap_username", imap_password: "imap_password", daily_limit: "daily_limit",
+};
+
+function normalizeSecurity(value, what) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const v = String(value).trim().toLowerCase().replace(/[\s_-]+/g, "");
+  if (["ssl", "ssl/tls", "tls", "ssltls", "implicit"].includes(v)) return "ssl";
+  if (["starttls", "start"].includes(v)) return "starttls";
+  if (["none", "no", "off", "plain"].includes(v)) return "none";
+  throw new Error(`${what} must be ssl, starttls or none`);
+}
+function parsePort(value, what) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const n = Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error(`${what} must be a port number from 1 to 65535`);
+  return n;
+}
+function parseDailyLimit(value) {
+  if (value === undefined || value === null || String(value).trim() === "") return undefined;
+  const n = Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1 || n > 10000) throw new Error("daily limit must be a whole number from 1 to 10000");
+  return n;
+}
+// One mailbox in the API's field names; empty values are left out (the server fills the defaults).
+function mailboxBody(f) {
+  const body = {};
+  const put = (k, v) => { if (v !== undefined && v !== null && String(v) !== "") body[k] = v; };
+  put("email", f.email ? String(f.email).trim().toLowerCase() : undefined);
+  put("display_name", f.sender_name ? String(f.sender_name).trim() : undefined);
+  put("preset", f.preset ? String(f.preset).trim().toLowerCase() : undefined);
+  put("smtp_host", f.smtp_host ? String(f.smtp_host).trim() : undefined);
+  put("smtp_port", parsePort(f.smtp_port, "smtp port"));
+  put("smtp_secure", normalizeSecurity(f.smtp_security, "smtp security"));
+  put("smtp_username", f.smtp_username ? String(f.smtp_username).trim() : undefined);
+  put("smtp_password", f.smtp_password);
+  put("imap_host", f.imap_host ? String(f.imap_host).trim() : undefined);
+  put("imap_port", parsePort(f.imap_port, "imap port"));
+  put("imap_secure", normalizeSecurity(f.imap_security, "imap security"));
+  put("imap_username", f.imap_username ? String(f.imap_username).trim() : undefined);
+  put("imap_password", f.imap_password);
+  put("daily_limit", parseDailyLimit(f.daily_limit));
+  if (!body.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(body.email)) throw new Error("needs a valid email address");
+  if (!body.smtp_password) throw new Error("needs a password");
+  if (!body.preset && !(body.smtp_host && body.smtp_port && body.imap_host)) {
+    throw new Error("needs a preset, or the sending server, its port and the server for reading replies");
+  }
+  return body;
+}
+
+// RFC 4180 CSV: quoted fields, doubled quotes, commas and line breaks inside quotes, CRLF, a BOM.
+function parseCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false, i = 0;
+  const src = String(text || "").replace(/^\uFEFF/, "");
+  while (i < src.length) {
+    const ch = src[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (src[i + 1] === '"') { field += '"'; i += 2; continue; }
+        quoted = false; i += 1; continue;
+      }
+      field += ch; i += 1; continue;
+    }
+    if (ch === '"' && field === "") { quoted = true; i += 1; continue; }
+    if (ch === ",") { row.push(field); field = ""; i += 1; continue; }
+    if (ch === "\r" && src[i + 1] === "\n") { i += 1; continue; }
+    if (ch === "\n" || ch === "\r") { row.push(field); rows.push(row); row = []; field = ""; i += 1; continue; }
+    field += ch; i += 1;
+  }
+  if (field !== "" || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((r) => r.some((v) => String(v).trim() !== ""));
+}
+
+// CSV text -> { rows: [{ line, body }], invalid: [{ line, email, message }], ignored: [column] }
+function mailboxesFromCsv(text) {
+  const table = parseCsv(text);
+  if (!table.length) throw new Error("the file is empty");
+  const header = table[0].map((h) => String(h).trim().toLowerCase().replace(/[\s-]+/g, "_"));
+  const fields = header.map((h) => SMTP_CSV_COLUMNS[h] || null);
+  if (!fields.includes("email")) throw new Error("the file needs an email column (see: argorant inboxes connect-smtp --help)");
+  const ignored = header.filter((h, i) => h && !fields[i]);
+  const rows = [], invalid = [];
+  table.slice(1).forEach((cells, index) => {
+    const line = index + 2;
+    const f = {};
+    fields.forEach((name, i) => { if (name && cells[i] !== undefined && String(cells[i]).trim() !== "") f[name] = name.endsWith("password") ? String(cells[i]) : String(cells[i]).trim(); });
+    try {
+      rows.push({ line, body: mailboxBody(f) });
+    } catch (e) {
+      invalid.push({ line, email: f.email || "", status: "invalid", message: e.message });
+    }
+  });
+  return { rows, invalid, ignored };
+}
+
+function promptSecret(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    let muted = false;
+    rl._writeToOutput = (str) => { if (!muted) rl.output.write(str); };
+    rl.question(question, (answer) => { rl.close(); process.stdout.write("\n"); resolve(answer); });
+    muted = true;
+  });
+}
+async function mailboxPassword(args, which) {
+  const envFlag = which === "imap" ? args.imapPasswordEnv : args.passwordEnv;
+  if (envFlag) {
+    const v = process.env[envFlag];
+    if (!v) die(`the environment variable ${envFlag} is empty or not set.`);
+    return v;
+  }
+  if (which === "imap") return undefined;   // the server uses the sending password
+  if (process.env.ARGORANT_MAILBOX_PASSWORD) return process.env.ARGORANT_MAILBOX_PASSWORD;
+  if (process.stdin.isTTY) {
+    const v = await promptSecret("Mailbox password or app password (not shown): ");
+    if (!v) die("no password given.");
+    return v;
+  }
+  die("give the mailbox password with --password-env NAME or the ARGORANT_MAILBOX_PASSWORD variable.");
+}
+
+function printSignInTest(t) {
+  if (!t || typeof t !== "object") return;
+  for (const [leg, label] of [["smtp", "sending"], ["imap", "reading replies"]]) {
+    const r = t[leg];
+    if (!r) continue;
+    console.log(`  ${r.works ? green("✓") : red("✗")} ${label.padEnd(16)}${r.message || r.result || ""}`);
+  }
+}
+function printBulkResults(results) {
+  const w = Math.min(40, Math.max(5, ...results.map((r) => String(r.email || "").length)));
+  for (const r of results) {
+    const mark = r.status === "connected" ? green("✓ connected") : r.status === "skipped" ? yellow("- skipped  ") : red("✗ " + (r.status === "invalid" ? "invalid  " : "failed   "));
+    console.log(`${String(r.line).padStart(4)}  ${String(r.email || "").padEnd(w)}  ${mark}  ${r.status === "connected" ? "" : (r.message || "")}`);
+  }
+}
+
+async function cmdSmtpMailbox(sub, argv, key) {
+  if (argv.includes("--password") || argv.some((a) => a.startsWith("--password="))) {
+    die("for safety the password is never taken on the command line. Use --password-env NAME, the ARGORANT_MAILBOX_PASSWORD variable, or type it when asked.");
+  }
+  if (argv.includes("--help") || argv.includes("-h")) return console.log(SMTP_USAGE + `
+
+  CSV columns: email, sender_name, preset, smtp_host, smtp_port, smtp_security, smtp_username, smtp_password,
+               imap_host, imap_port, imap_security, imap_username, imap_password, daily_limit
+  Each row needs email, smtp_password (or password), and a preset or smtp_host + smtp_port + imap_host.
+  Empty columns take the defaults: username = email, reading replies uses the sending sign-in, port 993, 25 a day.
+  Send on port 587 (starttls). If you give 465, Argorant tries 587 and saves 587 when it works.
+  Rows go up 25 at a time; each row says whether it connected or what to fix. Exit 1 when any row did not connect.`);
+  const args = readFlags(argv, SMTP_FLAGS);
+  if (args.csv) {
+    if (sub !== "connect-smtp") die("--csv works with connect-smtp.");
+    let text;
+    try { text = fs.readFileSync(args.csv, "utf8"); } catch (e) { die(`cannot read ${args.csv}: ${e.message}`); }
+    let parsed;
+    try { parsed = mailboxesFromCsv(text); } catch (e) { die(`${args.csv}: ${e.message}`); }
+    if (parsed.ignored.length && !args.json) warn(`ignoring unknown column${parsed.ignored.length === 1 ? "" : "s"}: ${parsed.ignored.join(", ")}`);
+    const results = [...parsed.invalid];
+    const totals = { connected: 0, failed: 0, skipped: 0, invalid: parsed.invalid.length };
+    for (let i = 0; i < parsed.rows.length; i += SMTP_BULK_CHUNK) {
+      const chunk = parsed.rows.slice(i, i + SMTP_BULK_CHUNK);
+      if (!args.json) process.stderr.write(dim(`checking ${i + 1} to ${i + chunk.length} of ${parsed.rows.length}...\n`));
+      const res = await request("POST", args.base, "/api/v1/inboxes/smtp/bulk", { key, body: { mailboxes: chunk.map((r) => r.body) } });
+      if (res.status >= 400) {
+        if (results.length && !args.json) printBulkResults(results.sort((a, b) => a.line - b.line));
+        need(res, "inboxes connect-smtp --csv");
+      }
+      const r = res.json || {};
+      for (const item of r.results || []) {
+        const source = chunk[Number(item.row) - 1];
+        results.push({ line: source ? source.line : null, email: item.email || (source && source.body.email), status: item.status, result: item.result, message: item.message });
+        if (item.status in totals) totals[item.status] += 1;
+      }
+    }
+    results.sort((a, b) => (a.line || 0) - (b.line || 0));
+    if (totals.failed || totals.invalid || totals.skipped) process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify({ ...totals, results }, null, 2));
+    printBulkResults(results);
+    const parts = [`${totals.connected} connected`];
+    if (totals.failed) parts.push(`${totals.failed} could not sign in`);
+    if (totals.skipped) parts.push(`${totals.skipped} skipped`);
+    if (totals.invalid) parts.push(`${totals.invalid} with missing or wrong columns`);
+    return console.log(`\n${parts.join(", ")}.`);
+  }
+  if (!args.email) die(SMTP_USAGE);
+  const password = await mailboxPassword(args, "smtp");
+  const imapPassword = await mailboxPassword(args, "imap");
+  let body;
+  try {
+    body = mailboxBody({
+      email: args.email, sender_name: args.name, preset: args.preset, smtp_host: args.smtpHost, smtp_port: args.smtpPort,
+      smtp_security: args.smtpSecurity, smtp_username: args.smtpUser, smtp_password: password, imap_host: args.imapHost,
+      imap_port: args.imapPort, imap_security: args.imapSecurity, imap_username: args.imapUser, imap_password: imapPassword,
+      daily_limit: args.dailyLimit,
+    });
+  } catch (e) {
+    die(`${e.message}.\n${SMTP_USAGE}`);
+  }
+  if (sub === "test-smtp") {
+    delete body.display_name; delete body.daily_limit;
+    const r = need(await request("POST", args.base, "/api/v1/inboxes/smtp/test", { key, body }), "inboxes test-smtp");
+    if (!r.works) process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify(r, null, 2));
+    console.log(`${r.works ? green("✓") : red("✗")} ${body.email}  ${r.message || ""}`);
+    printSignInTest(r);
+    if (r.works) console.log(dim(`Connect it:  argorant inboxes connect-smtp ${process.argv.slice(4).join(" ")}`.trim()));
+    return;
+  }
+  const res = await request("POST", args.base, "/api/v1/inboxes/smtp", { key, body });
+  if (res.status === 422 && errorCode(res.json) === "sign_in_failed") {
+    const details = (res.json && res.json.error && res.json.error.details) || {};
+    process.exitCode = 1;
+    if (args.json) return console.log(JSON.stringify({ connected: false, message: errorMessage(res.json), test: details.test || null }, null, 2));
+    console.log(`${red("✗")} ${body.email} was not connected. ${errorMessage(res.json) || ""}`);
+    printSignInTest(details.test);
+    return;
+  }
+  const r = need(res, "inboxes connect-smtp");
+  if (args.json) return console.log(JSON.stringify(r, null, 2));
+  const i = r.inbox || {};
+  console.log(green("✓") + ` Connected ${bold(i.email || body.email)}${i.daily_limit ? dim(`  ${i.daily_limit} a day`) : ""}`);
+  console.log(dim("It is in `argorant inboxes list` now and can be picked as a sender for any campaign."));
 }
 
 // =============================================================================
@@ -3082,8 +3434,9 @@ async function cmdCredits(argv) {
     return console.log(`
 ${bold("argorant credits")} packs                      ${dim("the credit packs and their prices")}
 ${bold("argorant credits")} quote <credits>            ${dim("a price quote for one pack; nothing is bought")}
-${bold("argorant credits")} buy <credits> [--pay-with link] [--yes]
-    ${dim("shows the quote, asks, then charges the saved card (when your workspace allows it) or gives you a payment link")}
+${bold("argorant credits")} buy <credits> [--pay-with link] [--yes] [--confirmation "<the user's yes>"]
+    ${dim("shows the quote, asks, then charges the saved card (when the account owner allowed it, up to a monthly limit) or gives you a payment link")}
+    ${dim("every purchase records its confirmation: your answer at the prompt, or the words passed with --confirmation")}
 ${bold("argorant credits")} purchases [<id>]           ${dim("purchases made with this account")}
 ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits stay valid for 365 days.")}
 `);
@@ -3100,7 +3453,7 @@ ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits st
     return;
   }
   if (sub === "quote" || sub === "buy") {
-    const args = readFlags(rest, { "--currency": "currency", "--pay-with": "payWith" });
+    const args = readFlags(rest, { "--currency": "currency", "--pay-with": "payWith", "--confirmation": "confirmation" });
     const credits = parseLimit(String(args._[0] || "").replace(/[,_]/g, "") || "x", "credits");
     const body = { credits };
     if (args.currency) body.currency = String(args.currency).toLowerCase();
@@ -3116,9 +3469,14 @@ ${dim("1 credit = 1 valid contact; 0.5 credit = 1 email check. Bought credits st
     if (!args.json) for (const l of quoteLines(q)) console.log(l);
     const card = q.payment && q.payment.saved_card;
     const how = payWith !== "link" && card && card.usable ? `The saved ${card.card || "card"} is charged now.` : "You get a payment link; nothing is charged before you pay it.";
-    if (!(await confirmOrDie(args, `Buy ${credits.toLocaleString()} credits for ${fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : q.pack || q, q.currency)}? ${how}`, "Buying credits needs a confirmation."))) return;
+    const question = `Buy ${credits.toLocaleString()} credits for ${fmtPrice(q.price_cents !== undefined || q.amount_cents !== undefined ? q : q.pack || q, q.currency)}? ${how}`;
+    if (!(await confirmOrDie(args, question, "Buying credits needs a confirmation."))) return;
     const pbody = { quote_id: q.quote_id, confirmed: true };
     if (payWith !== "auto") pbody.pay_with = payWith;
+    // The purchase records how it was confirmed (2026-10-07): the user's own words when an agent passes them,
+    // the answer at the prompt, or nothing extra with --yes (the record then says confirmed=true).
+    const said = args.confirmation ? String(args.confirmation) : !args.yes ? `Answered yes at the terminal to: ${question}` : "";
+    if (said.trim()) pbody.user_confirmation = said.replace(/\s+/g, " ").trim().slice(0, 1000);
     const r = need(await request("POST", args.base, `${V1}/credits/purchases`, { key, body: pbody }), "credit purchase");
     if (args.json) return console.log(JSON.stringify({ quote: q, purchase: r }, null, 2));
     const p = r.purchase && typeof r.purchase === "object" ? { ...r.purchase, ...r } : r;
@@ -3369,7 +3727,7 @@ ${bold("COMMANDS")}
   ${cyan("find")} status | download | resume | cancel <job_id>   Manage a find job ${dim("(free)")}
   ${cyan("find pricing")}               Finder prices, balance, limits ${dim("(free)")}
   ${cyan("campaigns")} ...                Email outreach: create, write, enroll, launch ${dim("(argorant campaigns help)")}
-  ${cyan("inboxes")} list | connect-google  Connected mailboxes; connect a Google Workspace
+  ${cyan("inboxes")} list | connect-google | connect-smtp | test-smtp   Connected mailboxes; connect Google Workspace or any provider
   ${cyan("inboxes")} quote | order | status | renewal  New mailboxes on new domains ${dim("(saved card or payment link)")}
   ${cyan("inbox")} list | read | reply | forward | classify   Replies across campaigns; answer in-thread or forward
   ${cyan("blocklist")} list | add | remove       Addresses and domains never contacted
@@ -3524,5 +3882,6 @@ if (require.main === module) {
     parseArgs, readFlags, flagValue, parseLimit, takeIdempotencyFlag, nextIdempotencyKey, isV1Write, IDEM,
     errorMessage, errorCode, requestIdOf, detailMsg, need, EXIT, request, pageQuery, pickItems, fetchPages, retryWaitSeconds, RATE_RETRY,
     companyFilters, numericId, fmtPrice, packLine, quoteLines, LOOKUP_KINDS, OWN_FLAG_COMMANDS, VERSION,
+    parseCsv, mailboxesFromCsv, mailboxBody, normalizeSecurity, SMTP_BULK_CHUNK,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argorant",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Search, count, reveal, export, and verify B2B contacts from the Argorant database, and find work emails by name and company domain, from your terminal, scripts, or coding agent.",
   "bin": {
     "argorant": "bin/argorant.js"
@@ -34,6 +34,7 @@
     "url": "https://argorant.com/docs/cli"
   },
   "scripts": {
-    "prepublishOnly": "node scripts/prepublish-guard.js"
+    "prepublishOnly": "node scripts/prepublish-guard.js",
+    "test": "node --test test/*.test.js"
   }
 }