groundmail-cli 0.32.3 → 0.33.0

package/README.md

@@ -75,6 +75,7 @@ groundmail domains list
 groundmail domains verify example.com
 groundmail webhooks list
 groundmail emails list
+groundmail senders list                                  # saved senders; send with --sender billing instead of --from
 SENDGRID_API_KEY=… groundmail migrate sendgrid --dry-run   # import from SendGrid, Postmark, Mailgun, Resend or Amazon SES (beta)
 ```
 

package/dist/cli.js

@@ -533,6 +533,7 @@ function parseSendCommandArgs(args) {
   const category = readFlag(args, "--category");
   return {
     from: readFlag(args, "--from"),
+    sender: readFlag(args, "--sender"),
     to: readFlag(args, "--to"),
     subject: readFlag(args, "--subject"),
     html: readFlag(args, "--html"),
@@ -564,7 +565,7 @@ async function runSendCommand(args, deps) {
     return 1;
   }
   if (options.fromDefaulted) {
-    stderr(`No --from: sending from the sandbox sender ${SANDBOX_FROM}, which only sends to your account email. Pass --from to send from your own domain.`);
+    stderr(`No --from: sending from the sandbox sender ${SANDBOX_FROM}, which only sends to your account email. Pass --from, or --sender with a saved sender, to send from your own domain.`);
   }
   const startedAt = now();
   const recipientDomain2 = options.to.split(",")[0]?.split("@")[1]?.replace(/>$/, "").trim();
@@ -572,7 +573,8 @@ async function runSendCommand(args, deps) {
   let result;
   try {
     result = await deps.sendEmail({
-      from: options.from,
+      ...options.from ? { from: options.from } : {},
+      ...options.sender ? { sender: options.sender } : {},
       to: options.to,
       subject: options.subject,
       html: options.html,
@@ -637,9 +639,11 @@ function parseSendCommandOptions(args, env) {
   if (!parsed.html && !parsed.text) {
     return { error: "Provide --html or --text" };
   }
+  const sender = parsed.sender?.trim() || void 0;
   return {
-    from: parsed.from || SANDBOX_FROM,
-    fromDefaulted: !parsed.from,
+    from: parsed.from || (sender ? void 0 : SANDBOX_FROM),
+    ...sender ? { sender } : {},
+    fromDefaulted: !parsed.from && !sender,
     to: parsed.to,
     subject: parsed.subject,
     html: parsed.html,
@@ -2051,7 +2055,7 @@ function trimUrl(value) {
 }
 
 // package.json
-var version = "0.32.3";
+var version = "0.33.0";
 
 // src/user-agent.ts
 function buildUserAgent(own) {
@@ -2135,15 +2139,15 @@ function parseArgs(argv, spec) {
   const booleanFlags = new Set(spec.booleans ?? []);
   const values = {};
   const booleans = {};
-  const positionals2 = [];
+  const positionals3 = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--") {
-      positionals2.push(...argv.slice(i + 1));
+      positionals3.push(...argv.slice(i + 1));
       break;
     }
     if (!arg.startsWith("--") || arg === "-") {
-      positionals2.push(arg);
+      positionals3.push(arg);
       continue;
     }
     const eq = arg.indexOf("=");
@@ -2169,7 +2173,7 @@ function parseArgs(argv, spec) {
     const known = [...valueFlags, ...booleanFlags].sort().join(", ");
     return { ok: false, error: `Unknown flag ${name}.${known ? ` This command takes: ${known}.` : ""}` };
   }
-  return { ok: true, args: { values, booleans, positionals: positionals2 } };
+  return { ok: true, args: { values, booleans, positionals: positionals3 } };
 }
 function wantsJson(args, stdout = process.stdout) {
   if (args.booleans["--json"] !== void 0) return args.booleans["--json"];
@@ -2477,10 +2481,10 @@ async function resolveAuth(flags, env = process.env, config = loadConfig(env)) {
   return fromSaved(current.workspace);
 }
 async function applySavedSession(argv, env = process.env, config) {
-  const hasFlag2 = (flag) => argv.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+  const hasFlag3 = (flag) => argv.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
   let workspace = null;
   let notice;
-  if (!hasFlag2("--api-key") && !envApiKey(env)) {
+  if (!hasFlag3("--api-key") && !envApiKey(env)) {
     const current = currentSavedWorkspace(config ?? loadConfig(env), env);
     if (current.ok) {
       workspace = current.workspace;
@@ -2491,7 +2495,7 @@ async function applySavedSession(argv, env = process.env, config) {
       notice = current.error;
     }
   }
-  if (hasFlag2("--base-url")) return { argv, notice };
+  if (hasFlag3("--base-url")) return { argv, notice };
   const url = explicitApiUrl(env) || trimUrl(workspace?.apiUrl) || trimUrl(env.GROUNDMAIL_DEFAULT_API_URL);
   return { argv: url ? [...argv, "--base-url", url] : argv, notice };
 }
@@ -3483,6 +3487,7 @@ async function runCreateCommand3(args, env = process.env) {
   const alias = readFlag20(args, "--alias");
   const category = readFlag20(args, "--category");
   const folder = readFlag20(args, "--folder");
+  const sender = readFlag20(args, "--sender");
   const unsubscribeEnabled = args.includes("--unsubscribe-enabled");
   if (!name) {
     return { exitCode: 1, error: 'Missing name. Pass --name "Welcome"' };
@@ -3503,7 +3508,8 @@ async function runCreateCommand3(args, env = process.env) {
       ...alias ? { alias } : {},
       ...category ? { category } : {},
       ...unsubscribeEnabled ? { unsubscribe_enabled: true } : {},
-      ...folder?.trim() ? { folder } : {}
+      ...folder?.trim() ? { folder } : {},
+      ...sender?.trim() ? { sender_id: sender.trim() } : {}
     });
     console.log(JSON.stringify(result));
     return { exitCode: 0 };
@@ -3524,7 +3530,8 @@ var POSITIONAL_FLAGS11 = [
   "--html",
   "--text",
   "--variable",
-  "--folder"
+  "--folder",
+  "--sender"
 ];
 async function runUpdateCommand4(args, env = process.env) {
   const options = parseTemplatesCommonArgs(args);
@@ -3544,12 +3551,13 @@ async function runUpdateCommand4(args, env = process.env) {
   const variables = readFlags3(args, "--variable");
   const category = readFlag20(args, "--category");
   const folder = readFlag20(args, "--folder");
+  const sender = readFlag20(args, "--sender");
   const unsubscribeEnabled = args.includes("--unsubscribe-enabled");
   const unsubscribeDisabled = args.includes("--no-unsubscribe-enabled");
-  if (!name && !subject && !html && !text && !alias && variables.length === 0 && !category && folder === void 0 && !unsubscribeEnabled && !unsubscribeDisabled) {
+  if (!name && !subject && !html && !text && !alias && variables.length === 0 && !category && folder === void 0 && sender === void 0 && !unsubscribeEnabled && !unsubscribeDisabled) {
     return {
       exitCode: 1,
-      error: "Nothing to update. Pass --name, --subject, --html, --text, --set-alias, --category, --variable, --folder, or unsubscribe flags."
+      error: "Nothing to update. Pass --name, --subject, --html, --text, --set-alias, --category, --variable, --folder, --sender, or unsubscribe flags."
     };
   }
   try {
@@ -3564,7 +3572,8 @@ async function runUpdateCommand4(args, env = process.env) {
       ...category ? { category } : {},
       ...unsubscribeEnabled ? { unsubscribe_enabled: true } : {},
       ...unsubscribeDisabled ? { unsubscribe_enabled: false } : {},
-      ...folder !== void 0 ? { folder } : {}
+      ...folder !== void 0 ? { folder } : {},
+      ...sender !== void 0 ? { sender_id: sender === "none" || !sender.trim() ? null : sender.trim() } : {}
     });
     console.log(JSON.stringify(result));
     return { exitCode: 0 };
@@ -3641,7 +3650,7 @@ async function runListStartersCommand(args, env = process.env) {
 }
 
 // src/commands/templates/versions.ts
-var POSITIONAL_FLAGS13 = ["--api-key", "--base-url", "--id", "--alias", "--version", "--from", "--to"];
+var POSITIONAL_FLAGS13 = ["--api-key", "--base-url", "--id", "--alias", "--version", "--from", "--sender", "--to"];
 function readFirstPositional14(args) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -3702,16 +3711,21 @@ async function runTestSendCommand(args, env = process.env) {
   }
   const idOrAlias = readFlag20(args, "--id") || readFlag20(args, "--alias") || readFirstPositional14(args);
   const from = readFlag20(args, "--from");
+  const sender = readFlag20(args, "--sender");
   const to = readFlag20(args, "--to");
-  if (!idOrAlias || !from || !to) {
+  if (!idOrAlias || !to) {
     return {
       exitCode: 1,
-      error: "Usage: groundmail templates test-send --id <id|alias> --from <email> --to <email>"
+      error: "Usage: groundmail templates test-send --id <id|alias> --to <email> [--from <email> | --sender <handle>] (neither: the template's sender, else your default sender)"
     };
   }
   try {
     const client2 = await createTemplatesClient(apiKey, options.baseUrl);
-    console.log(JSON.stringify(await client2.templates.testSend(idOrAlias, { from, to })));
+    console.log(
+      JSON.stringify(
+        await client2.templates.testSend(idOrAlias, { to, ...from ? { from } : {}, ...sender ? { sender } : {} })
+      )
+    );
     return { exitCode: 0 };
   } catch (error) {
     return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
@@ -3925,6 +3939,131 @@ async function runDomainsCommand(args, env = process.env) {
   };
 }
 
+// src/commands/senders/shared.ts
+var SENDER_VALUE_FLAGS = ["--api-key", "--base-url", "--id", "--name", "--address", "--reply-to", "--handle"];
+function readFlag22(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return void 0;
+  return args[index + 1];
+}
+function hasFlag2(args, flag) {
+  return args.includes(flag);
+}
+function positionals2(args, valueFlags = SENDER_VALUE_FLAGS) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      if (valueFlags.includes(arg)) i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+function parseSendersCommonArgs(args) {
+  return {
+    apiKey: readFlag22(args, "--api-key"),
+    baseUrl: readFlag22(args, "--base-url")
+  };
+}
+function resolveApiKey10(options, env) {
+  return options.apiKey || env.GROUNDMAIL_API_KEY || null;
+}
+async function createSendersClient(apiKey, baseUrl) {
+  const { Groundmail } = await import("groundmail");
+  return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
+}
+var MISSING_KEY2 = "Missing API key. Set GROUNDMAIL_API_KEY or pass --api-key.";
+function failure2(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = error?.hint;
+  return { exitCode: 1, error: typeof hint === "string" && hint ? `${message}
+${hint}` : message };
+}
+function senderRef(args) {
+  return readFlag22(args, "--id") || positionals2(args)[0];
+}
+function parseSenderFields(args) {
+  const name = readFlag22(args, "--name");
+  const address = readFlag22(args, "--address");
+  const replyTo = readFlag22(args, "--reply-to");
+  const handle = readFlag22(args, "--handle");
+  const makeDefault = hasFlag2(args, "--default");
+  const notDefault = hasFlag2(args, "--no-default");
+  if (makeDefault && notDefault) return { error: "Pass --default or --no-default, not both" };
+  return {
+    value: {
+      ...name !== void 0 ? { name } : {},
+      ...address !== void 0 ? { address } : {},
+      ...replyTo !== void 0 ? { reply_to: replyTo === "none" || replyTo === "" ? null : replyTo } : {},
+      ...handle !== void 0 ? { handle } : {},
+      ...makeDefault ? { is_default: true } : notDefault ? { is_default: false } : {}
+    }
+  };
+}
+
+// src/commands/senders/commands.ts
+async function withClient2(args, env, run) {
+  const options = parseSendersCommonArgs(args);
+  const apiKey = resolveApiKey10(options, env);
+  if (!apiKey) return { exitCode: 1, error: MISSING_KEY2 };
+  try {
+    const client2 = await createSendersClient(apiKey, options.baseUrl);
+    console.log(JSON.stringify(await run(client2)));
+    return { exitCode: 0 };
+  } catch (error) {
+    return failure2(error);
+  }
+}
+function missingSender(usage) {
+  return { exitCode: 1, error: `Missing sender (id or handle). Usage: ${usage}` };
+}
+async function runListCommand9(args, env = process.env) {
+  return withClient2(args, env, (client2) => client2.senders.list());
+}
+async function runCreateCommand5(args, env = process.env) {
+  const fields = parseSenderFields(args);
+  if ("error" in fields) return { exitCode: 1, error: fields.error };
+  const { name, address } = fields.value;
+  if (!name || !address) {
+    return {
+      exitCode: 1,
+      error: 'Required: --name and --address. Usage: groundmail senders create --name "Acme Billing" --address billing@mail.acme.com [--reply-to \u2026] [--handle billing] [--default]'
+    };
+  }
+  return withClient2(args, env, (client2) => client2.senders.create({ ...fields.value, name, address }));
+}
+async function runGetCommand8(args, env = process.env) {
+  const sender = senderRef(args);
+  if (!sender) return missingSender("groundmail senders get <id|handle>");
+  return withClient2(args, env, (client2) => client2.senders.get(sender));
+}
+async function runUpdateCommand6(args, env = process.env) {
+  const sender = senderRef(args);
+  if (!sender) return missingSender("groundmail senders update <id|handle> [--name \u2026] [--address \u2026] [--reply-to \u2026|none] [--handle \u2026] [--default]");
+  const fields = parseSenderFields(args);
+  if ("error" in fields) return { exitCode: 1, error: fields.error };
+  if (Object.keys(fields.value).length === 0) {
+    return {
+      exitCode: 1,
+      error: "Nothing to update. Pass --name, --address, --reply-to, --handle, --default or --no-default."
+    };
+  }
+  return withClient2(args, env, (client2) => client2.senders.update(sender, fields.value));
+}
+async function runDeleteCommand6(args, env = process.env) {
+  const sender = senderRef(args);
+  if (!sender) return missingSender("groundmail senders delete <id|handle> --yes");
+  if (!hasFlag2(args, "--yes")) {
+    return {
+      exitCode: 1,
+      error: `This deletes sender ${sender}. Sends that name it will fail. Run again with --yes to confirm.`
+    };
+  }
+  return withClient2(args, env, (client2) => client2.senders.remove(sender));
+}
+
 // src/commands/auth.ts
 async function runAuthCommand(subcommand, argv, deps = {}) {
   const env = deps.env ?? process.env;
@@ -4088,7 +4227,7 @@ function sesParams(args, env) {
       "Use a key with the read-only import policy (https://docs.groundmail.dev/migrations#amazon-ses-iam-policy). It is used for this import only and never stored."
     ].join("\n");
   }
-  const region = readFlag22(args, "--region") || env.AWS_REGION || env.AWS_DEFAULT_REGION;
+  const region = readFlag23(args, "--region") || env.AWS_REGION || env.AWS_DEFAULT_REGION;
   if (!region) return "Set the SES region with --region (for example --region us-east-1) or AWS_REGION. One region per import.";
   if (!AWS_REGION.test(region)) return `--region must be an AWS region such as us-east-1, not ${region}`;
   return {
@@ -4100,7 +4239,7 @@ function sesParams(args, env) {
   };
 }
 var VALUE_FLAGS3 = /* @__PURE__ */ new Set(["--api-key", "--base-url"]);
-function readFlag22(args, flag) {
+function readFlag23(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
@@ -4175,10 +4314,10 @@ function formatMigrationSummary(m) {
   return lines.join("\n");
 }
 async function client(args, env) {
-  const apiKey = readFlag22(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return null;
   const { Groundmail } = await import("groundmail");
-  const baseUrl = readFlag22(args, "--base-url");
+  const baseUrl = readFlag23(args, "--base-url");
   return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
 }
 async function runStoredCommand(sub, args, env) {
@@ -4215,7 +4354,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
     };
   }
   const id = provider;
-  const apiKey = readFlag22(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) {
     return { exitCode: 1, error: "Not signed in. Run `groundmail login`, or set GROUNDMAIL_API_KEY." };
   }
@@ -4225,7 +4364,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
     if (typeof ses === "string") return { exitCode: 1, error: ses };
     params = ses;
   } else {
-    const providerKey = readFlag22(args, "--key") || env[KEY_ENV[id]];
+    const providerKey = readFlag23(args, "--key") || env[KEY_ENV[id]];
     if (!providerKey) {
       const resend = id === "resend" ? " Use a key with Full access (Resend \u2192 API Keys); a Sending access key cannot read your account." : "";
       return {
@@ -4235,15 +4374,15 @@ async function runMigrateCommand(provider, args, env = process.env) {
     }
     params = { provider: id, api_key: providerKey };
     if (id === "postmark") {
-      const accountToken = readFlag22(args, "--account-token") || env.POSTMARK_ACCOUNT_TOKEN;
+      const accountToken = readFlag23(args, "--account-token") || env.POSTMARK_ACCOUNT_TOKEN;
       if (accountToken) params.account_api_key = accountToken;
     } else if (id === "sendgrid" || id === "mailgun") {
-      const region = readFlag22(args, "--region");
+      const region = readFlag23(args, "--region");
       if (region === "us" || region === "eu") params.region = region;
       else if (region) return { exitCode: 1, error: "--region must be us or eu" };
     }
   }
-  const only = readFlag22(args, "--only");
+  const only = readFlag23(args, "--only");
   if (only) {
     const list = only.split(",").map((s) => s.trim()).filter(Boolean);
     const bad = list.filter((r) => !RESOURCES.includes(r));
@@ -4255,7 +4394,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
   if (args.includes("--dry-run")) params.dry_run = true;
   try {
     const { Groundmail } = await import("groundmail");
-    const baseUrl = readFlag22(args, "--base-url");
+    const baseUrl = readFlag23(args, "--base-url");
     const client2 = new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
     console.error(`${params.dry_run ? "Previewing" : "Importing"} from ${LABELS[id]}${params.provider === "ses" ? ` (${params.aws_region})` : ""} (Beta)\u2026`);
     const report = await client2.migrations.run(params, {
@@ -4299,7 +4438,7 @@ async function runValidateCommand(args, env = process.env) {
 
 // src/commands/dmarc/dmarc.ts
 var DMARC_APPLY_PROVIDERS = ["cloudflare", "vercel", "godaddy", "netlify", "digitalocean", "dnsimple"];
-function readFlag23(args, flag) {
+function readFlag24(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
@@ -4356,23 +4495,23 @@ function formatDmarcStatus(dmarc) {
   return lines.join("\n");
 }
 async function runDmarcCommand(subcommand, args, env = process.env) {
-  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag24(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return { exitCode: 1, error: "Missing API key. Run groundmail login, set GROUNDMAIL_API_KEY or pass --api-key." };
-  const domain = readFlag23(args, "--domain") || readFirstPositional15(args);
+  const domain = readFlag24(args, "--domain") || readFirstPositional15(args);
   if (!subcommand || !["status", "enable", "disable", "digest"].includes(subcommand)) {
     return { exitCode: 1, error: "Usage: groundmail dmarc status|enable|disable|digest <domain>" };
   }
   if (!domain) return { exitCode: 1, error: `Missing domain. Usage: groundmail dmarc ${subcommand} example.com` };
   const json = args.includes("--json");
   try {
-    const client2 = await createDmarcClient(apiKey, readFlag23(args, "--base-url"));
+    const client2 = await createDmarcClient(apiKey, readFlag24(args, "--base-url"));
     if (subcommand === "status") {
       const result2 = await client2.dmarc.get(domain);
       console.log(json ? JSON.stringify(result2) : formatDmarcStatus(result2.dmarc));
       return { exitCode: 0 };
     }
     if (subcommand === "enable") {
-      const apply = readFlag23(args, "--apply");
+      const apply = readFlag24(args, "--apply");
       if (apply && !DMARC_APPLY_PROVIDERS.includes(apply)) {
         return { exitCode: 1, error: `--apply must be one of: ${DMARC_APPLY_PROVIDERS.join(", ")}` };
       }
@@ -4402,7 +4541,7 @@ Updated the DMARC record with ${result2.applied.provider}.`);
 }
 
 // src/commands/test-inbox/test-inbox.ts
-function readFlag24(args, flag) {
+function readFlag25(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
@@ -4430,20 +4569,20 @@ function formatTestEmail(email) {
 var USAGE = "Usage: groundmail test-inbox address [--prefix signup] | wait --to <address> [--timeout 30] [--since <iso>] [--json] | list [--to <address>] [--json]";
 async function runTestInboxCommand(subcommand, args, env = process.env) {
   if (!subcommand || !["address", "wait", "list"].includes(subcommand)) return { exitCode: 1, error: USAGE };
-  const apiKey = readFlag24(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag25(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return { exitCode: 1, error: "Missing API key. Run groundmail login, set GROUNDMAIL_API_KEY or pass --api-key." };
   const json = args.includes("--json");
   try {
-    const client2 = await createTestInboxClient(apiKey, readFlag24(args, "--base-url"));
+    const client2 = await createTestInboxClient(apiKey, readFlag25(args, "--base-url"));
     if (subcommand === "address") {
-      console.log(await client2.testInbox.address({ prefix: readFlag24(args, "--prefix") }));
+      console.log(await client2.testInbox.address({ prefix: readFlag25(args, "--prefix") }));
       return { exitCode: 0 };
     }
     if (subcommand === "list") {
       const result = await client2.testInbox.list({
-        to: readFlag24(args, "--to"),
-        since: readFlag24(args, "--since"),
-        limit: readFlag24(args, "--limit") ? Number(readFlag24(args, "--limit")) : void 0
+        to: readFlag25(args, "--to"),
+        since: readFlag25(args, "--since"),
+        limit: readFlag25(args, "--limit") ? Number(readFlag25(args, "--limit")) : void 0
       });
       if (json) console.log(JSON.stringify(result));
       else if (!result.emails.length) console.log("No test emails yet.");
@@ -4454,13 +4593,13 @@ async function runTestInboxCommand(subcommand, args, env = process.env) {
       }
       return { exitCode: 0 };
     }
-    const to = readFlag24(args, "--to");
+    const to = readFlag25(args, "--to");
     if (!to) return { exitCode: 1, error: "Missing --to. Usage: groundmail test-inbox wait --to signup-k3m9x2pq@acme.test.groundmail.dev" };
-    const timeoutRaw = readFlag24(args, "--timeout");
+    const timeoutRaw = readFlag25(args, "--timeout");
     const seconds = timeoutRaw === void 0 ? 30 : Number(timeoutRaw);
     if (!Number.isFinite(seconds) || seconds < 0) return { exitCode: 1, error: "--timeout must be a number of seconds" };
     try {
-      const email = await client2.testInbox.waitFor({ to, timeout: seconds * 1e3, since: readFlag24(args, "--since") });
+      const email = await client2.testInbox.waitFor({ to, timeout: seconds * 1e3, since: readFlag25(args, "--since") });
       console.log(json ? JSON.stringify({ email }) : formatTestEmail(email));
       return { exitCode: 0 };
     } catch (error) {
@@ -4501,7 +4640,7 @@ var USAGE_LINES = [
   "  groundmail test-inbox address [--prefix signup]   a fresh address on your team's test domain (mail there is caught, never delivered)",
   "  groundmail test-inbox wait --to <address> [--timeout 30] [--since <iso>] [--json]   wait for an email; prints its code and links (exit 2 on timeout)",
   "  groundmail test-inbox list [--to <address>] [--since <iso>] [--json]",
-  '  groundmail emails send [--from you@domain.com] --to user@example.com --subject "Hello" --html "<p>Hi</p>" [--category transactional|product|newsletter] [--unsubscribe] [--tenant <tenant>] [--watch [--timeout 60] [--json]]   no --from: the sandbox sender (to your account email only)',
+  `  groundmail emails send [--from you@domain.com | --sender billing] --to user@example.com --subject "Hello" --html "<p>Hi</p>" [--category transactional|product|newsletter] [--unsubscribe] [--tenant <tenant>] [--watch [--timeout 60] [--json]]   --sender: a saved sender's handle; no --from or --sender: the sandbox sender (to your account email only)`,
   '  groundmail emails send --to you@example.com --subject "Hello" --text "Hi" --watch   watch it land: the receiving server, its reply and the time',
   "  groundmail emails batch --file ./emails.json [--tenant <tenant>]",
   "  groundmail emails list [--limit 25] [--cursor \u2026] [--test | --live] [--tenant <tenant>] [--stream transactional|product|newsletter]",
@@ -4534,14 +4673,14 @@ var USAGE_LINES = [
   "  groundmail templates list [--status draft|published]",
   "  groundmail templates starters",
   "  groundmail templates from-starter password-reset",
-  '  groundmail templates create --name Welcome --subject "Hi" --html "<p>Hi</p>" [--category transactional|product] [--unsubscribe-enabled] [--folder Onboarding]',
+  '  groundmail templates create --name Welcome --subject "Hi" --html "<p>Hi</p>" [--category transactional|product] [--unsubscribe-enabled] [--folder Onboarding] [--sender billing]',
   "  groundmail templates get --id tpl_\u2026",
-  "  groundmail templates update --id tpl_\u2026 [--name \u2026] [--subject \u2026] [--html \u2026] [--text \u2026] [--set-alias \u2026] [--category transactional|product] [--unsubscribe-enabled|--no-unsubscribe-enabled] [--folder \u2026]",
+  "  groundmail templates update --id tpl_\u2026 [--name \u2026] [--subject \u2026] [--html \u2026] [--text \u2026] [--set-alias \u2026] [--category transactional|product] [--unsubscribe-enabled|--no-unsubscribe-enabled] [--folder \u2026] [--sender billing|none]",
   "  groundmail templates publish --id tpl_\u2026",
   `  groundmail templates push ./emails/welcome.tsx --alias welcome [--subject "Welcome"] [--props '{"name":"Ada"}'] [--publish]`,
   "  groundmail templates versions --id tpl_\u2026",
   "  groundmail templates restore --id tpl_\u2026 --version 2",
-  "  groundmail templates test-send --id tpl_\u2026 --from you@domain.com --to you@domain.com",
+  "  groundmail templates test-send --id tpl_\u2026 --to you@domain.com [--from you@domain.com | --sender billing]   neither: the template's sender, else your default sender",
   '  groundmail templates duplicate --id tpl_\u2026 [--name "Copy"]',
   "  groundmail templates delete --id tpl_\u2026",
   "  groundmail tenants list [--status active|paused] [--limit 25] [--cursor \u2026]   your customers, each with its own domains, suppressions and limits",
@@ -4555,6 +4694,11 @@ var USAGE_LINES = [
   "  groundmail tenants domains list <tenant>",
   "  groundmail tenants domains add <tenant> example.com   only this tenant can then send from it",
   "  groundmail tenants domains remove <tenant> example.com   gives the domain back to the account",
+  "  groundmail senders list   the names and addresses your email goes out as",
+  '  groundmail senders create --name "Acme Billing" --address billing@mail.acme.com [--reply-to billing@acme.com] [--handle billing] [--default]   address on a verified domain',
+  "  groundmail senders get <id|handle>",
+  "  groundmail senders update <id|handle> [--name \u2026] [--address \u2026] [--reply-to \u2026|none] [--handle \u2026] [--default|--no-default]",
+  "  groundmail senders delete <id|handle> --yes   refused while an automation or template uses it",
   "  groundmail keys list",
   "  groundmail keys create [--name Default] [--scopes emails:send,domains:read] [--allowed-domains example.com] [--test] [--tenant <tenant>]   --test: a gm_test_ key, sends are simulated; --tenant: a key limited to one tenant",
   "  groundmail keys delete --id <api-key-id>",
@@ -4597,7 +4741,8 @@ var ALIASES = {
   automations: { add: "create", remove: "delete" },
   suppressions: { create: "add", delete: "remove" },
   templates: { add: "create", remove: "delete" },
-  tenants: { add: "create", remove: "delete" }
+  tenants: { add: "create", remove: "delete" },
+  senders: { add: "create", remove: "delete" }
 };
 function words(line) {
   return line.trim().split(/\s+/);
@@ -4935,6 +5080,13 @@ async function main() {
     if (subcommand === "stats") await finish(await runStatsCommand(rest));
     if (subcommand === "domains") await finish(await runDomainsCommand(rest));
   }
+  if (command === "senders") {
+    if (subcommand === "list") await finish(await runListCommand9(rest));
+    if (subcommand === "create" || subcommand === "add") await finish(await runCreateCommand5(rest));
+    if (subcommand === "get") await finish(await runGetCommand8(rest));
+    if (subcommand === "update") await finish(await runUpdateCommand6(rest));
+    if (subcommand === "delete" || subcommand === "remove") await finish(await runDeleteCommand6(rest));
+  }
   if (command === "keys") {
     if (subcommand === "list") {
       const result = await runListKeysCommandWithClient(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-cli",
-  "version": "0.32.3",
+  "version": "0.33.0",
   "description": "Groundmail CLI — send transactional email from the terminal",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "groundmail": "0.33.0"
+    "groundmail": "0.34.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",