mailfully 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# Mailfully CLI
+
+Send transactional email and manage your Mailfully account from the terminal.
+Built on [`@mailfully/node`](https://www.npmjs.com/package/@mailfully/node).
+
+## Install
+
+```bash
+npm install -g mailfully
+```
+
+Requires Node.js 24 or newer.
+
+## Quickstart
+
+```bash
+mailfully login                      # paste an API key from the dashboard
+mailfully send --from you@yourdomain.dev --to someone@example.com \
+  --subject "Hello" --text "Sent from the Mailfully CLI."
+```
+
+## Authentication
+
+The CLI resolves an API key in this order:
+
+1. `--api-key <key>` on any command
+2. the `MAILFULLY_API_KEY` environment variable
+3. the key stored by `mailfully login` (`~/.config/mailfully/config.json`)
+
+Keys are minted in the [dashboard](https://dashboard.mailfully.com) and carry
+either the `live` or `test` environment. `mf_test_` keys exercise the full
+send path against the SES mailbox simulator — free and reputation-safe.
+`mailfully whoami` shows which key and API the CLI is talking to, and every
+send confirmation names the environment it went to.
+
+`mailfully login` stores the key in plaintext at
+`~/.config/mailfully/config.json` (file mode 600), like `gh` or `wrangler`.
+On shared machines prefer the interactive prompt or the environment variable
+over `--api-key`, which lands the key in shell history.
+
+Key management, webhooks, and suppression edits require a dashboard session
+(API keys cannot carry `manage:*` scopes), so those live in the dashboard, not
+the CLI.
+
+## Commands
+
+```
+mailfully login | logout | whoami
+mailfully send …                     # shorthand for emails send
+mailfully emails send|batch|get|list|events|cancel|reschedule
+mailfully domains add|list|get|verify|tracking
+mailfully templates create|list|get|update|delete
+mailfully suppressions list
+mailfully analytics daily|domains|tags|reputation
+```
+
+Every command that talks to the API accepts `--json`, `--api-key`, and `--api-url`. Run
+`mailfully <command> --help` for the full flag list.
+
+`--json` prints the raw API response for single calls (stable under the API's
+`/v1` versioning). Two shapes are CLI-synthesized instead: `--all` merges
+every page into one `{ "data": [...] }`, and `whoami` reports the CLI's own
+view. Only data goes to stdout — hints and errors go to stderr, so piped
+output stays clean.
+
+## Examples
+
+```bash
+# Verify a new sending domain
+mailfully domains add acme.dev --mail-from-prefix send
+mailfully domains verify dom_…
+
+# Send with a stored template, idempotently
+mailfully send --from you@acme.dev --to user@example.com \
+  --template tmpl_… --var name=Ada --idempotency-key signup-1042
+
+# Ship a batch from a file (a JSON array of API-shape email objects)
+mailfully emails batch ./welcome-batch.json --idempotency-key batch-2026-07-28
+
+# Investigate a delivery
+mailfully emails list --search user@example.com
+mailfully emails events em_…
+
+# Watch deliverability
+mailfully analytics daily --since 2026-07-01
+mailfully analytics reputation
+```
+
+## Exit codes
+
+`0` success · `1` API or network failure · `2` usage error · `3` accepted, but
+nothing will be sent.
+
+`3` means the API accepted the request and every recipient was suppressed, so
+no mail goes out — `send` on a fully suppressed message, or `emails batch`
+where *every* row was canceled (a partial batch stays `0`, because some mail
+did go out). It is distinct from `1` on purpose: `1` is the API refusing you,
+`3` is the API accepting you and dispatching nothing. Without it,
+`mailfully send … && next-step` would treat zero delivery as success.
+
+Scripts should treat any nonzero code as failure — finer-grained codes may be
+added in future minor versions.
+
+## Documentation
+
+- [Quickstart](https://mailfully.com/docs/quickstart)
+- [Verify a sending domain](https://mailfully.com/docs/guides/verify-a-domain) —
+  what `mailfully domains add` / `verify` are doing
+- [Test mode](https://mailfully.com/docs/guides/test-mode) — `mf_test_` keys,
+  which never touch your reputation or your bill
+- [Batch sending](https://mailfully.com/docs/guides/batch-sending) — the JSON
+  shape `mailfully emails batch` expects
+- [Idempotency](https://mailfully.com/docs/concepts/idempotency) —
+  `--idempotency-key`
+- [Error types](https://mailfully.com/docs/concepts/errors) and
+  [rate limits](https://mailfully.com/docs/concepts/rate-limits) — what the
+  CLI's error hints are pointing at
+- [Full API reference](https://mailfully.com/docs)
+
+Homepage: [mailfully.com](https://mailfully.com) ·
+Dashboard: [dashboard.mailfully.com](https://dashboard.mailfully.com) ·
+Issues: [github.com/Mailfully/mailfully/issues](https://github.com/Mailfully/mailfully/issues)
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { defaultConfigPath } from "./config.js";
+import { runCli } from "./program.js";
+import { cliVersion } from "./version.js";
+// engines.node is advisory only — npx on an old LTS would otherwise die with a
+// cryptic runtime error instead of this sentence.
+const major = Number(process.versions.node.split(".")[0] ?? "0");
+if (major < 24) {
+    process.stderr.write(`mailfully requires Node.js 24 or newer (you are running ${process.versions.node}).\n`);
+    process.exit(1);
+}
+/**
+ * The production fetch seam: a 60s timeout (an interactive CLI must never hang
+ * forever on a stalled connection) and a User-Agent identifying the CLI
+ * version on every request (so wire behavior can be debugged/deprecated per
+ * installed version later). Tests inject their own fetchImpl and bypass this.
+ */
+const realFetch = (input, init) => {
+    // A Headers merge, not a plain-object spread: init.headers can legitimately
+    // arrive as a Headers instance (case-insensitive, non-enumerable via
+    // spread), and spreading it would silently drop every header it carries —
+    // including a caller's Authorization.
+    const headers = new Headers(init?.headers);
+    headers.set("User-Agent", `mailfully-cli/${cliVersion()}`);
+    return fetch(input, {
+        ...init,
+        headers,
+        signal: AbortSignal.timeout(60_000),
+    });
+};
+process.exitCode = await runCli(process.argv.slice(2), {
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    fetchImpl: realFetch,
+    configPath: defaultConfigPath(process.env),
+});

package/dist/commands/analytics.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+export declare function registerAnalyticsCommands(program: Command, deps: ProgramDeps): void;

package/dist/commands/analytics.js

@@ -0,0 +1,97 @@
+import { resolveContext } from "../context.js";
+import { unwrap } from "../failure.js";
+import { formatTable, toJson } from "../output.js";
+import { withGlobalOptions } from "../flags.js";
+const COUNTER_HEADER = [
+    "Sent",
+    "Delivered",
+    "Bounced",
+    "Complained",
+    "Opened",
+    "Clicked",
+];
+function counterCells(c) {
+    return [
+        String(c.sent),
+        String(c.delivered),
+        String(c.bounced),
+        String(c.complained),
+        String(c.opened),
+        String(c.clicked),
+    ];
+}
+function windowQuery(opts) {
+    return {
+        ...(opts.since !== undefined ? { from: opts.since } : {}),
+        ...(opts.until !== undefined ? { to: opts.until } : {}),
+    };
+}
+// --since/--until, matching emails list (never --from, which means an address
+// on send); the wire params stay from/to.
+function withWindowOptions(cmd) {
+    return cmd
+        .option("--since <date>", "Window start (ISO date, e.g. 2026-07-01).")
+        .option("--until <date>", "Window end (ISO date).");
+}
+export function registerAnalyticsCommands(program, deps) {
+    const analytics = program
+        .command("analytics")
+        .description("Read delivery analytics rollups.");
+    withGlobalOptions(withWindowOptions(analytics.command("daily").description("Daily send/delivery counters."))).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.analytics.daily(windowQuery(opts)));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(["Day", ...COUNTER_HEADER], data.data.map((row) => [row.day, ...counterCells(row)])));
+    });
+    withGlobalOptions(withWindowOptions(analytics
+        .command("domains")
+        .description("Counters broken down by recipient domain.")
+        .option("--domain <domain>", "Filter to one recipient domain."))).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.analytics.byDomain({
+            ...windowQuery(opts),
+            ...(opts.domain !== undefined ? { domain: opts.domain } : {}),
+        }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(["Domain", "Day", ...COUNTER_HEADER], data.data.map((row) => [row.domain, row.day, ...counterCells(row)])));
+    });
+    withGlobalOptions(withWindowOptions(analytics
+        .command("tags")
+        .description("Counters broken down by tag.")
+        .option("--tag <tag>", "Filter to one tag value."))).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.analytics.byTag({
+            ...windowQuery(opts),
+            ...(opts.tag !== undefined ? { tag: opts.tag } : {}),
+        }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(["Tag", "Day", ...COUNTER_HEADER], data.data.map((row) => [row.tag, row.day, ...counterCells(row)])));
+    });
+    withGlobalOptions(analytics
+        .command("reputation")
+        .description("Latest external (Gmail Postmaster) reputation per domain.")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.analytics.externalReputation());
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(["Domain", "Gmail spam rate", "Observed"], data.data.domains.map((d) => [
+            d.domain,
+            d.gmailSpamRate === null ? "n/a" : String(d.gmailSpamRate),
+            d.observedAt,
+        ])));
+        if (data.data.worstGmailSpamRate !== null) {
+            deps.stdout.write(`\nWorst Gmail spam rate: ${data.data.worstGmailSpamRate}\n`);
+        }
+    });
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+export declare function registerAuthCommands(program: Command, deps: ProgramDeps): void;

package/dist/commands/auth.js

@@ -0,0 +1,82 @@
+import { Mailfully } from "@mailfully/node";
+import { deleteConfig, loadConfig, saveConfig } from "../config.js";
+import { keyEnvironment, redactKey, resolveBaseUrl, resolveContext, } from "../context.js";
+import { CommandFailure } from "../failure.js";
+import { renderError, toJson } from "../output.js";
+import { promptSecret } from "../prompt.js";
+import { withGlobalOptions } from "../flags.js";
+/**
+ * Verify a key by hitting the cheapest authenticated read. There is no
+ * dedicated identity endpoint on the v1 API, so `GET /v1/domains` is the
+ * probe (requires `send` OR `read:emails`). A 403 `insufficient_scope`
+ * response means the key AUTHENTICATED but lacks a scope for this endpoint —
+ * legitimately mintable (e.g. an analytics-only key), so it counts as valid.
+ * Note a revoked key also comes back 403, but with type `invalid_api_key`,
+ * so the type check below correctly rejects it.
+ */
+async function assertKeyUsable(client) {
+    const { error } = await client.domains.list();
+    if (error === null)
+        return;
+    if (error.statusCode === 403 && error.type === "insufficient_scope")
+        return;
+    throw new CommandFailure(renderError(error));
+}
+export function registerAuthCommands(program, deps) {
+    withGlobalOptions(program
+        .command("login")
+        .description("Store an API key for future commands (verified first).")).action(async (opts) => {
+        const prompt = deps.promptSecret ?? promptSecret;
+        const apiKey = opts.apiKey ??
+            (await prompt("Paste an API key from the dashboard (input hidden): "));
+        if (apiKey === "") {
+            throw new CommandFailure("No API key provided.", 2);
+        }
+        // Probe target honors the same flag > env > config precedence the rest of
+        // the CLI uses (resolveBaseUrl is shared with resolveContext), so a
+        // rotated key is verified against the server the CLI will actually talk
+        // to. Only an explicit --api-url is persisted.
+        const existing = await loadConfig(deps.configPath);
+        const probeUrl = resolveBaseUrl(opts.apiUrl, deps.env, existing);
+        await assertKeyUsable(new Mailfully({
+            apiKey,
+            ...(probeUrl !== undefined ? { baseUrl: probeUrl } : {}),
+            ...(deps.fetchImpl !== undefined ? { fetch: deps.fetchImpl } : {}),
+        }));
+        await saveConfig(deps.configPath, {
+            ...existing,
+            api_key: apiKey,
+            ...(opts.apiUrl !== undefined ? { base_url: opts.apiUrl } : {}),
+        });
+        deps.stdout.write(`Logged in with ${redactKey(apiKey)} (${keyEnvironment(apiKey)} environment).\n`);
+        if (opts.apiUrl === undefined && deps.env.MAILFULLY_API_URL !== undefined) {
+            // The env var steered the probe but is deliberately not persisted —
+            // otherwise unsetting it later would silently retarget the stored key.
+            deps.stdout.write(`Verified against ${deps.env.MAILFULLY_API_URL} (from MAILFULLY_API_URL — not stored; pass --api-url to store it).\n`);
+        }
+    });
+    // Deliberate exception: logout takes no global flags — it is purely local
+    // (deletes the config file) and never talks to the API.
+    program
+        .command("logout")
+        .description("Remove the stored API key.")
+        .action(async () => {
+        const removed = await deleteConfig(deps.configPath);
+        deps.stdout.write(removed ? "Logged out.\n" : "No stored credentials found.\n");
+    });
+    withGlobalOptions(program
+        .command("whoami")
+        .description("Show which key and API the CLI is talking to.")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        await assertKeyUsable(ctx.client);
+        if (ctx.json) {
+            deps.stdout.write(toJson({
+                key: redactKey(ctx.apiKey),
+                environment: ctx.environment,
+                base_url: ctx.baseUrl,
+            }));
+            return;
+        }
+        deps.stdout.write(`Authenticated with ${redactKey(ctx.apiKey)} (${ctx.environment} environment) against ${ctx.baseUrl}.\n`);
+    });
+}

package/dist/commands/domains.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+export declare function registerDomainsCommands(program: Command, deps: ProgramDeps): void;

package/dist/commands/domains.js

@@ -0,0 +1,135 @@
+import { resolveContext } from "../context.js";
+import { CommandFailure, unwrap } from "../failure.js";
+import { formatTable, toJson } from "../output.js";
+import { withGlobalOptions } from "../flags.js";
+/** The DNS records table (Priority is blank for non-MX records). */
+function recordsTable(records) {
+    return formatTable(["Type", "Name", "Value", "Priority"], records.map((r) => [
+        r.type,
+        r.name,
+        r.value,
+        r.priority === undefined ? "" : String(r.priority),
+    ]));
+}
+/** The one-domain-per-row summary used by `domains list`. */
+function domainCells(d) {
+    return [
+        d.id,
+        d.name,
+        d.status,
+        d.dkim_status,
+        d.mail_from_status,
+        d.tracking_enabled ? "on" : "off",
+        d.created_at,
+    ];
+}
+const DOMAIN_HEADER = [
+    "ID",
+    "Name",
+    "Status",
+    "DKIM",
+    "Mail from",
+    "Tracking",
+    "Created",
+];
+export function registerDomainsCommands(program, deps) {
+    const domains = program
+        .command("domains")
+        .description("Add and verify sending domains.");
+    withGlobalOptions(domains
+        .command("add")
+        .description("Add a sending domain and print the DNS records to publish.")
+        .argument("<name>", "The domain name, e.g. acme.dev.")
+        .option("--mail-from-prefix <label>", "Custom MAIL FROM subdomain label (a single DNS label, e.g. send).")).action(async (name, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.domains.create({
+            name,
+            ...(opts.mailFromPrefix !== undefined
+                ? { mailFromPrefix: opts.mailFromPrefix }
+                : {}),
+        }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`Added ${data.name} (${data.id}, status: ${data.status}).\n\n`);
+        deps.stdout.write("Publish these DNS records:\n\n");
+        deps.stdout.write(recordsTable(data.records));
+        deps.stdout.write(`\nThen run: mailfully domains verify ${data.id}\n`);
+    });
+    withGlobalOptions(domains.command("list").description("List this org's sending domains.")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.domains.list());
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(DOMAIN_HEADER, data.data.map(domainCells)));
+    });
+    withGlobalOptions(domains
+        .command("get")
+        .description("Show one domain's detail and DNS records.")
+        .argument("<id>", "The domain id (dom_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.domains.get(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write([
+            `ID:         ${data.id}`,
+            `Name:       ${data.name}`,
+            `Status:     ${data.status}`,
+            `DKIM:       ${data.dkim_status}`,
+            `Mail from:  ${data.mail_from_status} (${data.mail_from_subdomain ?? "default"})`,
+            // `tracking_status` is deliberately NOT shown. It is a column no
+            // production code path writes (the sole writer in the repo is the dev
+            // seed), so it reads `not_started` on every real domain forever —
+            // printing it rendered as the nonsense "Tracking: on (not_started)".
+            // `tracking_enabled` is the real signal and is the one shown.
+            `Tracking:   ${data.tracking_enabled ? "on" : "off"}`,
+            `Created:    ${data.created_at}`,
+        ].join("\n") + "\n\nDNS records:\n\n");
+        deps.stdout.write(recordsTable(data.records));
+    });
+    withGlobalOptions(domains
+        .command("verify")
+        .description("Ask Mailfully to re-check the domain's DNS now.")
+        .argument("<id>", "The domain id (dom_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.domains.verify(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`${data.name}: ${data.status} (DKIM ${data.dkim_status}, mail from ${data.mail_from_status}).\n`);
+        if (data.status !== "verified") {
+            deps.stdout.write("DNS can take a while to propagate — rerun this command to check again.\n");
+        }
+    });
+    withGlobalOptions(domains
+        .command("tracking")
+        .description("Turn open/click tracking on or off for a domain.")
+        .argument("<id>", "The domain id (dom_…).")
+        .option("--enable", "Turn tracking on.")
+        .option("--disable", "Turn tracking off.")).action(async (id, opts) => {
+        const enable = opts.enable === true;
+        const disable = opts.disable === true;
+        if (enable === disable) {
+            throw new CommandFailure("Pass exactly one of --enable or --disable.", 2);
+        }
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.domains.tracking(id, { enabled: enable }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(
+        // No `tracking_status` here either — see the note in `domains show`.
+        `Tracking for ${data.name} is now ${data.tracking_enabled ? "on" : "off"}.\n`);
+        if (data.records.length > 0) {
+            deps.stdout.write("\nDNS records:\n\n");
+            deps.stdout.write(recordsTable(data.records));
+        }
+    });
+}

package/dist/commands/emails.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+export declare function registerEmailsCommands(program: Command, deps: ProgramDeps): void;