groundmail-cli 0.30.0 → 0.31.0

package/README.md

@@ -47,6 +47,23 @@ Or without a global install:
 npx groundmail-cli emails send --from … --to … --subject … --html …
 ```
 
+## Watch an email land
+
+Add `--watch` to see the recipient's mail server accept it, with its real reply and the time it took:
+
+```bash
+groundmail emails send --to you@gmail.com --subject "Hello" --text "Hi" --watch
+```
+
+```
+  ✓ accepted by Groundmail                    0.3s
+  ✓ delivering to gmail-smtp-in.l.google.com
+  ✓ 250 2.0.0 OK  1793… - gsmtp               2.9s
+  Delivered to you@gmail.com in 2.9s.
+```
+
+Without `--from`, it sends from the sandbox sender (`noreply@mail.groundmail.dev`) to your own account email, so it works right after `groundmail login`. Deferrals show the server's reply and keep watching; a bounce prints the exact reply, the bounce type and what to do. `groundmail emails get <id> --watch` follows an email you already sent; `--json` prints one JSON object per stage; `--timeout <seconds>` (default 60). Exit codes: `0` delivered, `1` error, `3` bounced or failed, `4` still on its way, `5` test send.
+
 ## Common commands
 
 ```bash

package/dist/cli.js

@@ -1,7 +1,505 @@
 #!/usr/bin/env node
 import "./chunk-4SSJDDBV.js";
 
+// src/commands/emails/watch.ts
+var WATCH_EXIT = {
+  /** The recipient's mail server accepted it. */
+  delivered: 0,
+  /** The send or a status check failed: bad flags, sign-in, the API refused the send. */
+  error: 1,
+  /** It bounced, failed, was suppressed or was cancelled. */
+  notDelivered: 3,
+  /** Still on its way when `--timeout` ran out. */
+  timeout: 4,
+  /** A test send: simulated, never delivered. */
+  test: 5
+};
+var DEFAULT_WATCH_TIMEOUT_SECONDS = 60;
+var LABEL_WIDTH = 42;
+function formatDuration(ms) {
+  const clamped = Math.max(0, ms);
+  if (clamped < 6e4) return `${(clamped / 1e3).toFixed(1)}s`;
+  const minutes = Math.floor(clamped / 6e4);
+  const seconds = Math.floor(clamped % 6e4 / 1e3);
+  return `${minutes}m ${seconds}s`;
+}
+function between(from, to) {
+  if (!from || !to) return null;
+  const a = Date.parse(from);
+  const b = Date.parse(to);
+  return Number.isFinite(a) && Number.isFinite(b) ? Math.max(0, b - a) : null;
+}
+function timedFrom(email) {
+  const scheduled = email.scheduled_at ? Date.parse(email.scheduled_at) : NaN;
+  return Number.isFinite(scheduled) && scheduled > Date.parse(email.created_at) ? email.scheduled_at : email.created_at;
+}
+var ID_LIKE = /^[A-Za-z0-9][A-Za-z0-9._\-=+/]{7,}$/;
+function idLike(token) {
+  return ID_LIKE.test(token) && /\d/.test(token) && !/^\d\.\d{1,3}\.\d{1,3}$/.test(token);
+}
+function shortenReply(reply, max) {
+  if (reply.length <= LABEL_WIDTH) return reply;
+  const parts = reply.split(/(\s+)/);
+  const out = [];
+  let inRun = false;
+  for (const part of parts) {
+    if (/^\s+$/.test(part)) {
+      if (!inRun) out.push(part);
+      continue;
+    }
+    if (idLike(part)) {
+      if (!inRun) out.push(`${part.slice(0, 4)}\u2026`);
+      inRun = true;
+      continue;
+    }
+    if (inRun) out.push(" ");
+    inRun = false;
+    out.push(part);
+  }
+  const collapsed = out.join("").replace(/ +$/, "");
+  if (collapsed.length <= max) return collapsed;
+  const keep = max - 1;
+  const head = Math.ceil(keep * 0.7);
+  return `${collapsed.slice(0, head)}\u2026${collapsed.slice(collapsed.length - (keep - head))}`;
+}
+var SPINNER = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var MARK_TEXT = { ok: "\u2713", fail: "\u2717", warn: "!", wait: "\u2192" };
+var MARK_COLOR = { ok: "32", fail: "31", warn: "33", wait: "36" };
+var Renderer = class {
+  constructor(io, now, spinnerMs) {
+    this.io = io;
+    this.now = now;
+    this.live = null;
+    this.lastPlainLive = null;
+    this.frame = 0;
+    this.timer = null;
+    if (io.isTTY && spinnerMs > 0) {
+      this.timer = setInterval(() => {
+        this.frame = (this.frame + 1) % SPINNER.length;
+        this.drawLive();
+      }, spinnerMs);
+      this.timer.unref?.();
+    }
+  }
+  paint(code, text) {
+    return this.io.isTTY && this.io.color !== false ? `\x1B[${code}m${text}\x1B[0m` : text;
+  }
+  layout(prefix, label, time) {
+    if (!time) return `  ${prefix} ${label}`;
+    const gap = label.length < LABEL_WIDTH ? " ".repeat(LABEL_WIDTH - label.length) : "  ";
+    return `  ${prefix} ${label}${gap}${this.paint("2", time)}`;
+  }
+  clearLive() {
+    if (this.io.isTTY && this.live) this.io.write("\r\x1B[2K");
+  }
+  drawLive() {
+    if (!this.io.isTTY || !this.live) return;
+    const spinner = this.paint("36", SPINNER[this.frame]);
+    this.io.write(`\r\x1B[2K${this.layout(spinner, this.live.label, formatDuration(this.now() - this.live.since))}`);
+  }
+  /** A finished line. */
+  line(mark, label, ms) {
+    this.clearLive();
+    this.io.write(`${this.layout(this.paint(MARK_COLOR[mark], MARK_TEXT[mark]), label, ms == null ? null : formatDuration(ms))}
+`);
+    this.drawLive();
+  }
+  /** An indented detail under the last line (a server reply, say). */
+  detail(text) {
+    this.clearLive();
+    this.io.write(`    ${text}
+`);
+    this.drawLive();
+  }
+  /** A sentence after the lines (the outcome and what to do). */
+  note(text) {
+    this.clearLive();
+    this.io.write(`  ${text}
+`);
+    this.drawLive();
+  }
+  /** The waiting line. Plain output prints it once per new label. */
+  waiting(label, since) {
+    if (!this.io.isTTY) {
+      if (label !== this.lastPlainLive) this.io.write(`${this.layout(MARK_TEXT.wait, label, null)}
+`);
+      this.lastPlainLive = label;
+      return;
+    }
+    if (this.live?.label === label) return;
+    this.live = { label, since: this.live?.since ?? since };
+    this.drawLive();
+  }
+  /** The waiting line is done: on a terminal it becomes a finished line. */
+  settle(mark, label) {
+    if (!this.live) return;
+    const text = label ?? this.live.label;
+    this.clearLive();
+    this.live = null;
+    if (this.io.isTTY) this.io.write(`${this.layout(this.paint(MARK_COLOR[mark], MARK_TEXT[mark]), text, null)}
+`);
+  }
+  get plainLive() {
+    return this.lastPlainLive;
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.clearLive();
+    this.live = null;
+  }
+};
+var TROUBLESHOOTING_URL = "https://docs.groundmail.dev/troubleshooting#emails-arent-arriving";
+function looksTooLarge(text) {
+  return /\b552\b[^\n]*\b5\.3\.4\b|\b5\.2\.3\b|message size|too large|size exceeds/i.test(text ?? "");
+}
+function outcomeAdvice(email) {
+  const recipient = email.to[0] ?? "the address";
+  const reply = email.delivery?.response ?? email.bounce_reason ?? "";
+  if (email.status === "suppressed") {
+    return `Not sent: a recipient is on your suppression list. Remove the suppression only if you know the address works now: groundmail suppressions remove --email ${recipient}`;
+  }
+  if (email.status === "cancelled") return "Cancelled before it went out.";
+  if (email.bounce_type === "block") {
+    return `Bounced (block): the receiving server refused the sender, not the address. ${recipient} isn't suppressed and this doesn't count toward your bounce rate; send to it again later. More: ${TROUBLESHOOTING_URL}`;
+  }
+  if (email.bounce_type === "hard") {
+    return `Bounced (hard): the address can't receive mail, so it's on your suppression list now and later sends to it are skipped. Check it for typos, and remove the suppression only if you know it works: groundmail suppressions remove --email ${recipient}`;
+  }
+  if (looksTooLarge(reply)) {
+    return "Failed: the receiving server refused it for its size. The address is fine and not suppressed: send a smaller email, and link to large files instead of attaching them.";
+  }
+  return `Failed: it wasn't delivered and the address isn't suppressed. The reason is above; more: ${TROUBLESHOOTING_URL}`;
+}
+var DELIVERED_STATUSES = /* @__PURE__ */ new Set(["delivered", "opened", "clicked", "complained"]);
+var FAILED_STATUSES = /* @__PURE__ */ new Set(["bounced", "failed", "suppressed", "cancelled"]);
+var NOT_ACCEPTED = /* @__PURE__ */ new Set(["queued", "scheduled", "suppressed", "cancelled"]);
+function pollDelayMs(elapsedMs) {
+  if (elapsedMs < 1e4) return 400;
+  if (elapsedMs < 2e4) return 1e3;
+  if (elapsedMs < 3e4) return 2e3;
+  if (elapsedMs < 6e4) return 3e3;
+  return 5e3;
+}
+var RATE_LIMITED_DELAY_MS = 5e3;
+var MX_WAIT_MS = 1500;
+function recipientDomain(to) {
+  const first = to?.[0]?.split(",")[0]?.trim() ?? "";
+  const at = first.lastIndexOf("@");
+  const domain = at === -1 ? "" : first.slice(at + 1).replace(/>$/, "").trim().toLowerCase();
+  return domain || null;
+}
+async function lookupMx(domain) {
+  try {
+    const { resolveMx } = await import("dns/promises");
+    const records = await resolveMx(domain);
+    const best = records.sort((a, b) => a.priority - b.priority)[0]?.exchange?.replace(/\.$/, "").toLowerCase();
+    return best || null;
+  } catch {
+    return null;
+  }
+}
+function withTimeout(promise, ms) {
+  if (ms <= 0) return Promise.resolve(TIMED_OUT);
+  let timer;
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    new Promise((resolve) => {
+      timer = setTimeout(() => resolve(TIMED_OUT), ms);
+    })
+  ]);
+}
+var TIMED_OUT = /* @__PURE__ */ Symbol("timed out");
+function errorStatus(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : null;
+}
+async function watchEmail(options, deps) {
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const io = deps.io;
+  const json = options.json;
+  const stderr = deps.stderr ?? ((line) => console.error(line));
+  const watchStart = now();
+  const deadline = watchStart + options.timeoutMs;
+  let startedAt = options.startedAt ?? watchStart;
+  const sinceAccepted = (email) => {
+    if (options.startedAt !== void 0) return;
+    const created = Date.parse(email.created_at);
+    if (Number.isFinite(created)) startedAt = Math.min(created, watchStart);
+  };
+  const render = new Renderer(json ? { ...io, isTTY: false } : io, now, json ? 0 : deps.spinnerMs ?? 80);
+  const emit = (stage) => io.write(`${JSON.stringify(stage)}
+`);
+  let mx = options.mx ?? null;
+  const startMx = (to) => {
+    if (mx || !deps.resolveMx) return;
+    const domain = recipientDomain(to);
+    if (domain) mx = deps.resolveMx(domain).catch(() => null);
+  };
+  startMx(options.to);
+  let accepted = false;
+  let heldShown = false;
+  let deliveringShown = null;
+  const deferrals = /* @__PURE__ */ new Set();
+  let lastStatus = "queued";
+  let mxHost = null;
+  let mxSettled = false;
+  const finish2 = (code) => {
+    render.stop();
+    return code;
+  };
+  const awaitMx = async () => {
+    if (mxSettled) return;
+    mxSettled = true;
+    if (!mx) return;
+    const result = await withTimeout(mx, Math.min(MX_WAIT_MS, Math.max(0, deadline - now())));
+    mxHost = result === TIMED_OUT ? null : result;
+  };
+  const showDelivering = (email, retrying) => {
+    const host = email.delivery?.receiving_server ?? mxHost;
+    const target = host ?? `the mail server for ${recipientDomain(email.to) ?? "the recipient"}`;
+    if (json) {
+      if (host && deliveringShown !== host) emit({ stage: "delivering", id: email.id, receiving_server: host });
+    } else {
+      render.waiting(retrying ? `retrying delivery to ${target}` : `delivering to ${target}`, startedAt);
+    }
+    deliveringShown = host ?? deliveringShown;
+  };
+  const step = async (email) => {
+    lastStatus = email.status;
+    startMx(email.to);
+    sinceAccepted(email);
+    if (email.test) {
+      if (json) emit({ stage: "test", id: email.id, status: email.status });
+      else render.note(TEST_SEND_NOTE);
+      return WATCH_EXIT.test;
+    }
+    if (!accepted && !NOT_ACCEPTED.has(email.status) && !(email.status === "failed" && !email.sent_at)) {
+      accepted = true;
+      const ms = between(timedFrom(email), email.sent_at);
+      if (json) emit({ stage: "accepted", id: email.id, status: email.status, created_at: email.created_at, sent_at: email.sent_at, elapsed_ms: ms });
+      else render.line("ok", "accepted by Groundmail", ms);
+      for (const held of email.held_back ?? []) {
+        if (json) emit({ stage: "held_back", id: email.id, email: held.email, reason: held.reason });
+        else render.line("warn", `not sent to ${held.email} (${held.reason})`);
+      }
+    }
+    if (email.status === "scheduled") {
+      const at = email.scheduled_at ? Date.parse(email.scheduled_at) : NaN;
+      if (Number.isFinite(at) && at > deadline + 1e3) {
+        if (json) emit({ stage: "scheduled", id: email.id, scheduled_at: email.scheduled_at, check: `groundmail emails get ${email.id} --watch` });
+        else {
+          render.stop();
+          render.note(`Scheduled for ${email.scheduled_at}. Watch it then: groundmail emails get ${email.id} --watch`);
+        }
+        return WATCH_EXIT.timeout;
+      }
+      if (!json) render.waiting(`scheduled for ${email.scheduled_at ?? "later"}`, startedAt);
+      return null;
+    }
+    const delivery = email.delivery ?? null;
+    if (delivery?.deferred_at && !deferrals.has(delivery.deferred_at)) {
+      const first = deferrals.size === 0;
+      deferrals.add(delivery.deferred_at);
+      const ms = between(timedFrom(email), delivery.deferred_at);
+      const host = delivery.receiving_server ?? "the receiving server";
+      if (json) {
+        emit({ stage: "deferred", id: email.id, receiving_server: delivery.receiving_server, response: delivery.deferred_response, deferred_at: delivery.deferred_at, elapsed_ms: ms });
+      } else {
+        render.line("warn", `deferred by ${host}`, ms);
+        render.detail(delivery.deferred_response ?? "no reply: the connection failed or timed out");
+        if (first) render.note("Delivery is retried automatically.");
+      }
+    } else if (email.status === "delayed" && !deferrals.size) {
+      deferrals.add("status");
+      if (json) emit({ stage: "deferred", id: email.id, receiving_server: null, response: null, deferred_at: null, elapsed_ms: null });
+      else {
+        render.line("warn", "deferred by the receiving server");
+        render.note("Delivery is retried automatically.");
+      }
+    }
+    const landed = DELIVERED_STATUSES.has(email.status) || Boolean(email.delivered_at) && !FAILED_STATUSES.has(email.status);
+    if (landed) {
+      await awaitMx();
+      const host = delivery?.receiving_server ?? mxHost;
+      const ms = between(timedFrom(email), email.delivered_at);
+      const to = email.to.join(", ");
+      if (json) {
+        emit({
+          stage: "delivered",
+          id: email.id,
+          to: email.to,
+          receiving_server: host,
+          response: delivery?.response ?? null,
+          tls: delivery?.tls ?? null,
+          delivered_at: email.delivered_at,
+          elapsed_ms: ms
+        });
+        return WATCH_EXIT.delivered;
+      }
+      const deliveringLabel = host ? `delivering to ${host}` : "delivering to the recipient's mail server";
+      if (io.isTTY) {
+        render.waiting(deliveringLabel, startedAt);
+        render.settle("ok", deliveringLabel);
+      } else if (render.plainLive !== deliveringLabel) {
+        render.line("ok", deliveringLabel);
+      }
+      const reply = delivery?.response;
+      const label = reply ? io.isTTY ? shortenReply(reply, Math.max(LABEL_WIDTH, (io.columns ?? 80) - 14)) : reply : "accepted by the receiving server";
+      render.line("ok", label, ms);
+      render.note(ms == null ? `Delivered to ${to}.` : `Delivered to ${to} in ${formatDuration(ms)}.`);
+      return finish2(WATCH_EXIT.delivered);
+    }
+    if (FAILED_STATUSES.has(email.status)) {
+      const host = delivery?.receiving_server ?? null;
+      const reply = delivery?.response ?? email.bounce_reason ?? null;
+      const ms = between(timedFrom(email), email.bounced_at);
+      const advice = outcomeAdvice(email);
+      if (json) {
+        emit({
+          stage: email.status,
+          id: email.id,
+          status: email.status,
+          bounce_type: email.bounce_type ?? null,
+          receiving_server: host,
+          response: reply,
+          elapsed_ms: ms,
+          advice
+        });
+        return WATCH_EXIT.notDelivered;
+      }
+      render.stop();
+      const label = email.status === "cancelled" ? "cancelled" : email.status === "suppressed" ? "not sent" : host ? `refused by ${host}` : email.sent_at ? "refused by the receiving server" : "not sent";
+      render.line("fail", label, ms);
+      if (reply) render.detail(reply);
+      render.note(advice);
+      return finish2(WATCH_EXIT.notDelivered);
+    }
+    if (email.status === "held") {
+      if (!heldShown) {
+        heldShown = true;
+        if (json) emit({ stage: "held", id: email.id });
+        else {
+          render.line("warn", "held before sending");
+          render.note("Held for content review, or sending is paused on the account. It goes out or is rejected after review.");
+        }
+      }
+      if (!json) render.waiting("held, waiting for review", startedAt);
+      return null;
+    }
+    if (email.status === "queued") {
+      if (!json) render.waiting("queued", startedAt);
+      return null;
+    }
+    await awaitMx();
+    showDelivering(email, deferrals.size > 0);
+    return null;
+  };
+  let consecutiveErrors = 0;
+  let lastError = null;
+  for (; ; ) {
+    const remaining = deadline - now();
+    let result = null;
+    let rateLimited = false;
+    try {
+      result = await withTimeout(deps.getEmail(options.id), Math.max(remaining, 1));
+      consecutiveErrors = 0;
+    } catch (error) {
+      const status = errorStatus(error);
+      const message = error instanceof Error ? error.message : String(error);
+      if (status !== null && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+        render.stop();
+        const hint = error.hint;
+        if (json) emit({ stage: "error", id: options.id, status, code: error.code ?? null, message, hint: hint ?? null });
+        else {
+          stderr(message);
+          if (hint) stderr(hint);
+        }
+        return WATCH_EXIT.error;
+      }
+      rateLimited = status === 429;
+      consecutiveErrors += 1;
+      lastError = message;
+    }
+    if (result && result !== TIMED_OUT) {
+      const code = await step(result.email);
+      if (code !== null) return finish2(code);
+    }
+    if (now() >= deadline || result === TIMED_OUT) break;
+    const base = pollDelayMs(now() - watchStart);
+    const delay = rateLimited ? Math.max(RATE_LIMITED_DELAY_MS, base) : consecutiveErrors ? Math.min(5e3, base * 2 ** consecutiveErrors) : base;
+    await sleep(Math.min(delay, Math.max(0, deadline - now())));
+    if (now() >= deadline) {
+      const last = await withTimeout(deps.getEmail(options.id), 2e3).catch(() => null);
+      if (last && last !== TIMED_OUT) {
+        const code = await step(last.email);
+        if (code !== null) return finish2(code);
+      }
+      break;
+    }
+  }
+  const waited = now() - watchStart;
+  render.settle("wait");
+  render.stop();
+  if (json) {
+    emit({ stage: "timeout", id: options.id, status: lastStatus, waited_ms: waited, check: `groundmail emails get ${options.id}` });
+  } else {
+    render.note(`Still on its way after ${formatDuration(waited)} (status: ${lastStatus}). Check on it later:`);
+    render.note(`  groundmail emails get ${options.id}`);
+    if (consecutiveErrors && lastError) render.note(`(The last status check failed: ${lastError})`);
+  }
+  return WATCH_EXIT.timeout;
+}
+var TEST_SEND_NOTE = "Test send: simulated, never delivered. Test keys (gm_test_\u2026) and simulator addresses never reach a real mail server, so there is nothing to watch.";
+function reportTestSend(io, input) {
+  if (input.json) {
+    io.write(`${JSON.stringify({ stage: "test", id: input.id, status: input.status })}
+`);
+    return;
+  }
+  const render = new Renderer(io, Date.now, 0);
+  render.line("ok", "accepted by Groundmail (test send)");
+  render.note(TEST_SEND_NOTE);
+}
+function parseWatchTimeout(raw) {
+  if (raw === void 0) return { ms: DEFAULT_WATCH_TIMEOUT_SECONDS * 1e3 };
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds <= 0) return { error: "--timeout must be a number of seconds above 0" };
+  return { ms: Math.round(seconds * 1e3) };
+}
+function processWatchIo(env = process.env) {
+  return {
+    write: (text) => {
+      process.stdout.write(text);
+    },
+    isTTY: Boolean(process.stdout.isTTY) && env.TERM !== "dumb",
+    columns: process.stdout.columns,
+    color: !env.NO_COLOR
+  };
+}
+
 // src/commands/emails/send.ts
+var SANDBOX_FROM = "noreply@mail.groundmail.dev";
+function describeSendError(error) {
+  const e = error ?? {};
+  const message = error instanceof Error ? error.message : String(error);
+  const status = typeof e.status === "number" ? e.status : null;
+  const code = typeof e.code === "string" ? e.code : null;
+  const hint = typeof e.hint === "string" && e.hint ? e.hint : null;
+  const lines = [message];
+  if (status === 403 && /sandbox/i.test(message)) {
+    const account = message.match(/limited to (\S+@\S+?)\.(?:\s|$)/)?.[1];
+    lines.push(
+      `The sandbox sender (${SANDBOX_FROM}) only sends to your account email${account ? `, ${account}` : " (groundmail whoami shows it)"}. Watch one land there:`,
+      `  groundmail emails send --to ${account ?? "<your account email>"} --subject "Hello" --text "Hi" --watch`,
+      "To send to anyone else, verify your domain (groundmail domains add example.com), add a payment method at https://app.groundmail.dev/settings/billing, and pass --from you@example.com."
+    );
+  } else if (hint) {
+    lines.push(hint);
+  }
+  return { message, status, code, hint, lines };
+}
 function readFlag(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
@@ -52,13 +550,28 @@ async function runSendCommand(args, deps) {
   const env = deps.env ?? process.env;
   const stdout = deps.stdout ?? ((line) => console.log(line));
   const stderr = deps.stderr ?? ((line) => console.error(line));
+  const now = deps.now ?? Date.now;
   const options = parseSendCommandOptions(args, env);
   if ("error" in options) {
     stderr(options.error);
     return 1;
   }
+  const watch = args.includes("--watch");
+  const json = args.includes("--json");
+  const timeout = parseWatchTimeout(readFlag(args, "--timeout"));
+  if (watch && "error" in timeout) {
+    stderr(timeout.error);
+    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.`);
+  }
+  const startedAt = now();
+  const recipientDomain2 = options.to.split(",")[0]?.split("@")[1]?.replace(/>$/, "").trim();
+  const mx = watch && deps.resolveMx && recipientDomain2 ? deps.resolveMx(recipientDomain2).catch(() => null) : void 0;
+  let result;
   try {
-    const result = await deps.sendEmail({
+    result = await deps.sendEmail({
       from: options.from,
       to: options.to,
       subject: options.subject,
@@ -70,15 +583,43 @@ async function runSendCommand(args, deps) {
       unsubscribe: options.unsubscribe,
       ...options.tenant ? { tenant: options.tenant } : {}
     });
+  } catch (error) {
+    const described = describeSendError(error);
+    if (watch && json) {
+      stdout(JSON.stringify({ stage: "error", status: described.status, code: described.code, message: described.message, hint: described.hint }));
+    } else {
+      for (const line of described.lines) stderr(line);
+    }
+    return 1;
+  }
+  if (!watch) {
     stdout(JSON.stringify(result));
     if (result.test) {
       stderr("Test send: simulated, nothing was delivered. Its status and webhooks are marked test.");
     }
     return 0;
-  } catch (error) {
-    stderr(error instanceof Error ? error.message : String(error));
+  }
+  const io = deps.watchIo ?? processWatchIo(env);
+  if (result.test) {
+    reportTestSend(io, { id: result.id, status: result.status, json });
+    return WATCH_EXIT.test;
+  }
+  if (!deps.getEmail) {
+    stderr("--watch needs a client that can read the email.");
     return 1;
   }
+  return watchEmail(
+    { id: result.id, timeoutMs: "ms" in timeout ? timeout.ms : 6e4, json, startedAt, to: [options.to], mx },
+    {
+      getEmail: deps.getEmail,
+      resolveMx: deps.resolveMx,
+      io,
+      stderr,
+      now: deps.now,
+      sleep: deps.sleep,
+      spinnerMs: deps.spinnerMs
+    }
+  );
 }
 function parseSendCommandOptions(args, env) {
   const parsed = parseSendCommandArgs(args);
@@ -90,14 +631,15 @@ function parseSendCommandOptions(args, env) {
   if ("error" in parsedTags) {
     return { error: parsedTags.error };
   }
-  if (!parsed.from || !parsed.to || !parsed.subject) {
-    return { error: "Required flags: --from --to --subject (and --html or --text)" };
+  if (!parsed.to || !parsed.subject) {
+    return { error: `Required flags: --to --subject (and --html or --text). --from defaults to the sandbox sender ${SANDBOX_FROM} (your account email only).` };
   }
   if (!parsed.html && !parsed.text) {
     return { error: "Provide --html or --text" };
   }
   return {
-    from: parsed.from,
+    from: parsed.from || SANDBOX_FROM,
+    fromDefaulted: !parsed.from,
     to: parsed.to,
     subject: parsed.subject,
     html: parsed.html,
@@ -112,12 +654,12 @@ function parseSendCommandOptions(args, env) {
   };
 }
 function createDefaultSendDeps(apiKey, baseUrl) {
+  let client2 = null;
+  const getClient = () => client2 ?? (client2 = import("groundmail").then(({ Groundmail }) => new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0)));
   return {
-    sendEmail: async (params) => {
-      const { Groundmail } = await import("groundmail");
-      const client2 = new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
-      return client2.emails.send(params);
-    }
+    sendEmail: async (params) => (await getClient()).emails.send(params),
+    getEmail: async (id) => (await getClient()).emails.get(id),
+    resolveMx: lookupMx
   };
 }
 async function runSendCommandWithClient(args, env = process.env) {
@@ -294,16 +836,30 @@ async function runResendCommandWithClient(args, env = process.env) {
 }
 
 // src/commands/emails/get.ts
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["--id", "--api-key", "--base-url", "--timeout", "--workspace"]);
 function readFlag5(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
 }
+function emailIdFromArgs(args) {
+  const flagged = readFlag5(args, "--id");
+  if (flagged) return flagged;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (VALUE_FLAGS.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (!arg.startsWith("--")) return arg;
+  }
+  return void 0;
+}
 async function runGetCommand(args, deps) {
   const env = deps.env ?? process.env;
   const stdout = deps.stdout ?? ((line) => console.log(line));
   const stderr = deps.stderr ?? ((line) => console.error(line));
-  const id = readFlag5(args, "--id") || args.find((a) => !a.startsWith("--"));
+  const id = emailIdFromArgs(args);
   const apiKey = readFlag5(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) {
     stderr("Missing API key. Set GROUNDMAIL_API_KEY or pass --api-key.");
@@ -313,6 +869,26 @@ async function runGetCommand(args, deps) {
     stderr("Required: --id <msg_\u2026>");
     return { exitCode: 1, error: "missing id" };
   }
+  if (args.includes("--watch")) {
+    const timeout = parseWatchTimeout(readFlag5(args, "--timeout"));
+    if ("error" in timeout) {
+      stderr(timeout.error);
+      return { exitCode: 1, error: timeout.error };
+    }
+    const exitCode = await watchEmail(
+      { id, timeoutMs: timeout.ms, json: args.includes("--json") },
+      {
+        getEmail: deps.getEmail,
+        resolveMx: deps.resolveMx,
+        io: deps.watchIo ?? processWatchIo(env),
+        stderr,
+        now: deps.now,
+        sleep: deps.sleep,
+        spinnerMs: deps.spinnerMs
+      }
+    );
+    return { exitCode };
+  }
   try {
     const result = await deps.getEmail(id);
     stdout(JSON.stringify(result));
@@ -330,10 +906,12 @@ async function runGetCommandWithClient(args, env = process.env) {
   }
   const { Groundmail } = await import("groundmail");
   const client2 = new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
-  return runGetCommand(args, {
+  const result = await runGetCommand(args, {
     env,
-    getEmail: (id) => client2.emails.get(id)
+    getEmail: (id) => client2.emails.get(id),
+    resolveMx: lookupMx
   });
+  return { exitCode: result.exitCode };
 }
 
 // src/commands/emails/insights.ts
@@ -737,18 +1315,25 @@ async function createDomainsClient(apiKey, baseUrl) {
   const { Groundmail } = await import("groundmail");
   return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
 }
+function pushRecord(lines, record) {
+  lines.push(`  ${record.type.padEnd(6)} ${record.host}`);
+  if (record.type === "MX" && record.priority != null) {
+    lines.push(`         priority: ${record.priority}`);
+    lines.push(`         mail server: ${record.value}`);
+  } else {
+    lines.push(`         ${record.value}`);
+  }
+  lines.push(`         (${record.purpose})`);
+  lines.push("");
+}
 function formatDnsRecords(records) {
+  const toAdd = records.filter((record) => !record.already_set);
+  const alreadySet = records.filter((record) => record.already_set);
   const lines = ["DNS records to add:", ""];
-  for (const record of records) {
-    lines.push(`  ${record.type.padEnd(6)} ${record.host}`);
-    if (record.type === "MX" && record.priority != null) {
-      lines.push(`         priority: ${record.priority}`);
-      lines.push(`         mail server: ${record.value}`);
-    } else {
-      lines.push(`         ${record.value}`);
-    }
-    lines.push(`         (${record.purpose})`);
-    lines.push("");
+  for (const record of toAdd) pushRecord(lines, record);
+  if (alreadySet.length) {
+    lines.push("Already set, nothing to change:", "");
+    for (const record of alreadySet) pushRecord(lines, record);
   }
   return lines.join("\n").trimEnd();
 }
@@ -1466,7 +2051,7 @@ function trimUrl(value) {
 }
 
 // package.json
-var version = "0.30.0";
+var version = "0.31.0";
 
 // src/user-agent.ts
 function buildUserAgent(own) {
@@ -2774,7 +3359,7 @@ async function loadTemplateSource(filePath, options = {}, deps = {}) {
 }
 
 // src/commands/templates/push.ts
-var VALUE_FLAGS = /* @__PURE__ */ new Set([
+var VALUE_FLAGS2 = /* @__PURE__ */ new Set([
   "--alias",
   "--subject",
   "--name",
@@ -2788,7 +3373,7 @@ function readPositional(args) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg.startsWith("--")) {
-      if (VALUE_FLAGS.has(arg)) index += 1;
+      if (VALUE_FLAGS2.has(arg)) index += 1;
       continue;
     }
     return arg;
@@ -3485,7 +4070,7 @@ var KEY_ENV = {
   mailgun: "MAILGUN_API_KEY"
 };
 var LABELS = { sendgrid: "SendGrid", postmark: "Postmark", mailgun: "Mailgun" };
-var VALUE_FLAGS2 = /* @__PURE__ */ new Set(["--api-key", "--base-url"]);
+var VALUE_FLAGS3 = /* @__PURE__ */ new Set(["--api-key", "--base-url"]);
 function readFlag22(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
@@ -3572,7 +4157,7 @@ async function runStoredCommand(sub, args, env) {
       if (!data.length) console.error("No imports yet. Previews are not stored.");
       return { exitCode: 0 };
     }
-    const id = args.find((arg, i) => !arg.startsWith("--") && !VALUE_FLAGS2.has(args[i - 1] ?? ""));
+    const id = args.find((arg, i) => !arg.startsWith("--") && !VALUE_FLAGS3.has(args[i - 1] ?? ""));
     if (!id) return { exitCode: 1, error: "Usage: groundmail migrate report <import id> [--csv]" };
     if (args.includes("--csv")) {
       process.stdout.write(await gm.migrations.reportCsv(id));
@@ -3676,12 +4261,12 @@ function readFlag23(args, flag) {
   if (index === -1) return void 0;
   return args[index + 1];
 }
-var VALUE_FLAGS3 = ["--api-key", "--base-url", "--domain", "--apply"];
+var VALUE_FLAGS4 = ["--api-key", "--base-url", "--domain", "--apply"];
 function readFirstPositional15(args) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg.startsWith("--")) {
-      if (VALUE_FLAGS3.includes(arg)) i += 1;
+      if (VALUE_FLAGS4.includes(arg)) i += 1;
       continue;
     }
     return arg;
@@ -3873,11 +4458,12 @@ 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>]',
+  '  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 --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]",
   "  groundmail emails insights [--window 7d|30d]",
-  "  groundmail emails get --id msg_\u2026",
+  "  groundmail emails get --id msg_\u2026 [--watch [--timeout 60] [--json]]   --watch: follow an email you already sent until it lands",
   "  groundmail emails cancel --id msg_\u2026",
   "  groundmail emails resend --id msg_\u2026",
   `  groundmail events send --name user.created --email user@example.com --data '{"name":"Ada"}'`,
@@ -3953,6 +4539,8 @@ var FOOTER_LINES = [
   "",
   "<tenant>: the tenant's external id (your id for that customer) or its Groundmail id.",
   "",
+  "--watch exit codes: 0 delivered, 1 error, 3 bounced or failed, 4 still on its way at --timeout, 5 test send (never delivered).",
+  "",
   "Add --help to any command for just its usage. --version prints the CLI version."
 ];
 var CLI_VERSION = version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-cli",
-  "version": "0.30.0",
+  "version": "0.31.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.29.0"
+    "groundmail": "0.30.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",