shipmail-cli 0.1.3 → 0.1.5

package/README.md

@@ -40,6 +40,22 @@ shipmail messages send \
 shipmail inbox list mbx_123 --folder-role inbox --limit 25
 shipmail inbox thread mbx_123 thr_123
 
+# Find newsletter sending domain IDs, then create a draft with blocks
+shipmail newsletter-domains list
+shipmail newsletters create \
+  --audience-id aud_123 \
+  --newsletter-domain-id nwsdom_456 \
+  --name "July changelog" \
+  --subject "What shipped in July" \
+  --blocks @blocks.json
+shipmail newsletters update nws_123 --subject "Updated subject"
+shipmail newsletters preview nws_123
+shipmail newsletters test-send nws_123 --recipient-email owner@example.com
+shipmail newsletters preflight nws_123
+shipmail newsletters schedule nws_123 --scheduled-at 2026-08-01T09:00:00.000Z
+shipmail newsletter-assets list --kind image
+shipmail newsletter-assets upload ./hero.png --content-type image/png
+
 # Manage webhooks
 shipmail webhooks create \
   --url https://example.com/shipmail/webhook \
@@ -73,5 +89,8 @@ Use repeatable `--header "Name: value"` flags for request headers. Use `--output
 - `messages send|list|get`
 - `webhooks list|create|test|deliveries`
 - `suppressions list|remove`
+- `newsletter-domains list`
+- `newsletters create|update|preview|preflight|test-send|schedule|cancel|resume`
+- `newsletter-assets list|upload`
 
 Run `shipmail --help` for flags and examples.

package/dist/cli.js

@@ -12,7 +12,7 @@ import {
 } from "shipmail";
 
 // src/version.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.5";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -149,9 +149,95 @@ async function readJsonInput(value) {
   try {
     return JSON.parse(raw);
   } catch {
-    throw new CliUsageError("--data must be valid JSON or @path/to/file.json.");
+    throw new CliUsageError("Value must be valid JSON or @path/to/file.json.");
   }
 }
+async function readTextInput(value) {
+  if (value === void 0) return void 0;
+  if (value.startsWith("@")) return readFile(value.slice(1), "utf8");
+  return value;
+}
+async function readNewsletterBlocks(value) {
+  const parsed = await readJsonInput(value);
+  if (!Array.isArray(parsed)) {
+    throw new CliUsageError("--blocks must be a JSON array of newsletter blocks.");
+  }
+  if (parsed.length === 0) {
+    throw new CliUsageError("--blocks must include at least one block.");
+  }
+  return parsed;
+}
+function parseArchiveVisibility(options) {
+  const value = getString(options, "archive-visibility");
+  if (value === void 0) return void 0;
+  if (value === "private" || value === "public") return value;
+  throw new CliUsageError("--archive-visibility must be private or public.");
+}
+async function newsletterCreateParams(options) {
+  const audience_id = getRequiredString(options, "audience-id");
+  const newsletter_domain_id = getRequiredString(options, "newsletter-domain-id");
+  const name = getRequiredString(options, "name");
+  const subject = getRequiredString(options, "subject");
+  const blocksInput = getString(options, "blocks");
+  const bodyHtmlInput = getString(options, "body-html");
+  const bodyTextInput = getString(options, "body-text");
+  const blocks = blocksInput ? await readNewsletterBlocks(blocksInput) : void 0;
+  const body_html = bodyHtmlInput ? await readTextInput(bodyHtmlInput) : void 0;
+  const body_text = bodyTextInput ? await readTextInput(bodyTextInput) : void 0;
+  if (!blocks?.length && !body_html?.trim() && !body_text?.trim()) {
+    throw new CliUsageError("Provide at least one of --blocks, --body-html, or --body-text.");
+  }
+  const send_window_hours = getNumber(options, "send-window-hours");
+  const archive_visibility = parseArchiveVisibility(options);
+  const preview_text = getString(options, "preview-text");
+  const from_name = getString(options, "from-name");
+  return {
+    audience_id,
+    newsletter_domain_id,
+    name,
+    subject,
+    ...preview_text !== void 0 ? { preview_text } : {},
+    ...from_name !== void 0 ? { from_name } : {},
+    ...blocks ? { blocks } : {},
+    ...body_html !== void 0 ? { body_html } : {},
+    ...body_text !== void 0 ? { body_text } : {},
+    ...send_window_hours !== void 0 ? { send_window_hours } : {},
+    ...archive_visibility !== void 0 ? { archive_visibility } : {}
+  };
+}
+async function newsletterUpdateParams(options) {
+  const audience_id = getString(options, "audience-id");
+  const newsletter_domain_id = getString(options, "newsletter-domain-id");
+  const name = getString(options, "name");
+  const subject = getString(options, "subject");
+  const preview_text = getString(options, "preview-text");
+  const from_name = getString(options, "from-name");
+  const send_window_hours = getNumber(options, "send-window-hours");
+  const archive_visibility = parseArchiveVisibility(options);
+  const blocksInput = getString(options, "blocks");
+  const bodyHtmlInput = getString(options, "body-html");
+  const bodyTextInput = getString(options, "body-text");
+  const blocks = blocksInput ? await readNewsletterBlocks(blocksInput) : void 0;
+  const body_html = bodyHtmlInput ? await readTextInput(bodyHtmlInput) : void 0;
+  const body_text = bodyTextInput ? await readTextInput(bodyTextInput) : void 0;
+  const params = {
+    ...audience_id ? { audience_id } : {},
+    ...newsletter_domain_id ? { newsletter_domain_id } : {},
+    ...name ? { name } : {},
+    ...subject ? { subject } : {},
+    ...preview_text !== void 0 ? { preview_text } : {},
+    ...from_name !== void 0 ? { from_name } : {},
+    ...blocks ? { blocks } : {},
+    ...body_html !== void 0 ? { body_html } : {},
+    ...body_text !== void 0 ? { body_text } : {},
+    ...send_window_hours !== void 0 ? { send_window_hours } : {},
+    ...archive_visibility !== void 0 ? { archive_visibility } : {}
+  };
+  if (Object.keys(params).length === 0) {
+    throw new CliUsageError("Provide at least one field to update.");
+  }
+  return params;
+}
 function apiPath(rawPath) {
   if (!rawPath) throw new CliUsageError("Missing API path.");
   if (!rawPath.startsWith("/")) throw new CliUsageError("API path must start with '/'.");
@@ -242,6 +328,34 @@ Usage:
   shipmail webhooks create --url https://example.com/hook --events message.received,message.bounced
   shipmail suppressions list
   shipmail suppressions remove <email>
+  shipmail newsletters create \\
+    --audience-id aud_123 \\
+    --newsletter-domain-id nwsdom_456 \\
+    --name "July changelog" \\
+    --subject "What shipped in July" \\
+    --blocks @blocks.json
+  shipmail newsletters update nws_789 --subject "Updated subject" --blocks @blocks-v2.json
+  shipmail newsletters preview <id>
+  shipmail newsletters preflight <id>
+  shipmail newsletters test-send <id> --recipient-email owner@example.com
+  shipmail newsletters schedule <id> --scheduled-at 2026-08-01T09:00:00.000Z
+  shipmail newsletters cancel <id>
+  shipmail newsletters resume <id>
+  shipmail newsletter-assets list [--kind image|video] [--q text] [--limit 25] [--cursor cur]
+  shipmail newsletter-assets upload <file> [--filename name] [--content-type type]
+  shipmail newsletter-domains list [--limit 25] [--cursor cur]
+  shipmail audiences list [--limit 25] [--cursor cur]
+  shipmail audiences create <name> --consent-source "Signup form" [--description "..."]
+  shipmail audiences get <id>
+  shipmail audiences update <id> [--name "..."] [--description "..."]
+  shipmail audiences delete <id>
+  shipmail audiences subscribers add <audience-id> <email> [--name "Jane"] [--consent-source "..."]
+  shipmail audiences subscribers list <audience-id> [--status subscribed] [--email jane@x.com] [--limit 25]
+  shipmail audiences subscribers get <audience-id> <subscriber-id>
+  shipmail audiences subscribers by-email <audience-id> <email>
+  shipmail audiences subscribers update <audience-id> <subscriber-id> [--name "..."]
+  shipmail audiences subscribers unsubscribe <audience-id> <subscriber-id>
+  shipmail audiences subscribers remove <audience-id> <subscriber-id>
 
 Global options:
   --api-key <key>       API key. Defaults to SHIPMAIL_API_KEY.
@@ -575,6 +689,267 @@ async function runSuppressions(client, parsed, out) {
   }
   throw new CliUsageError("Unknown suppressions command.");
 }
+var SUBSCRIBER_STATUS_VALUES = [
+  "subscribed",
+  "unsubscribed",
+  "bounced",
+  "complained",
+  "suppressed",
+  "transactional_only"
+];
+function subscriberListParams(options) {
+  const email = getString(options, "email");
+  const statusRaw = getString(options, "status");
+  const status = statusRaw ? SUBSCRIBER_STATUS_VALUES.find((s) => s === statusRaw) : void 0;
+  if (statusRaw && !status) {
+    throw new CliUsageError(`Invalid --status: ${statusRaw}.`);
+  }
+  return {
+    cursor: getString(options, "cursor"),
+    limit: getNumber(options, "limit"),
+    ...status ? { status } : {},
+    ...email ? { email } : {}
+  };
+}
+async function runSubscribers(client, parsed, out) {
+  const action = parsed.positional[2];
+  const audienceId = requirePositional(parsed.positional, 3, "audience id");
+  if (action === "list") {
+    writeJson(
+      out,
+      await client.audiences.subscribers.list(audienceId, subscriberListParams(parsed.options))
+    );
+    return;
+  }
+  if (action === "add") {
+    const name = getString(parsed.options, "name");
+    const consentSource = getString(parsed.options, "consent-source");
+    const consentIp = getString(parsed.options, "consent-ip");
+    writeJson(
+      out,
+      await client.audiences.subscribers.add(audienceId, {
+        email_address: requirePositional(parsed.positional, 4, "email"),
+        ...name ? { display_name: name } : {},
+        ...consentSource ? { consent_source: consentSource } : {},
+        ...consentIp ? { consent_ip: consentIp } : {}
+      })
+    );
+    return;
+  }
+  if (action === "get") {
+    writeJson(
+      out,
+      await client.audiences.subscribers.get(
+        audienceId,
+        requirePositional(parsed.positional, 4, "subscriber id")
+      )
+    );
+    return;
+  }
+  if (action === "by-email") {
+    writeJson(
+      out,
+      await client.audiences.subscribers.getByEmail(
+        audienceId,
+        requirePositional(parsed.positional, 4, "email")
+      )
+    );
+    return;
+  }
+  if (action === "update") {
+    const subscriberId = requirePositional(parsed.positional, 4, "subscriber id");
+    const name = getString(parsed.options, "name");
+    writeJson(
+      out,
+      await client.audiences.subscribers.update(audienceId, subscriberId, {
+        ...name ? { display_name: name } : {}
+      })
+    );
+    return;
+  }
+  if (action === "unsubscribe") {
+    writeJson(
+      out,
+      await client.audiences.subscribers.unsubscribe(
+        audienceId,
+        requirePositional(parsed.positional, 4, "subscriber id")
+      )
+    );
+    return;
+  }
+  if (action === "remove") {
+    const subscriberId = requirePositional(parsed.positional, 4, "subscriber id");
+    await client.audiences.subscribers.remove(audienceId, subscriberId);
+    writeJson(out, { ok: true, id: subscriberId });
+    return;
+  }
+  throw new CliUsageError("Unknown audiences subscribers command.");
+}
+async function runAudiences(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "subscribers") {
+    await runSubscribers(client, parsed, out);
+    return;
+  }
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.audiences.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "create") {
+    const description = getString(parsed.options, "description");
+    writeJson(
+      out,
+      await client.audiences.create({
+        name: requirePositional(parsed.positional, 2, "audience name"),
+        consent_source: getRequiredString(parsed.options, "consent-source"),
+        ...description ? { description } : {}
+      })
+    );
+    return;
+  }
+  if (subcommand === "get") {
+    writeJson(
+      out,
+      await client.audiences.get(requirePositional(parsed.positional, 2, "audience id"))
+    );
+    return;
+  }
+  if (subcommand === "update") {
+    const id = requirePositional(parsed.positional, 2, "audience id");
+    const name = getString(parsed.options, "name");
+    const description = getString(parsed.options, "description");
+    writeJson(
+      out,
+      await client.audiences.update(id, {
+        ...name ? { name } : {},
+        ...description ? { description } : {}
+      })
+    );
+    return;
+  }
+  if (subcommand === "delete") {
+    const id = requirePositional(parsed.positional, 2, "audience id");
+    await client.audiences.delete(id);
+    writeJson(out, { ok: true, id });
+    return;
+  }
+  throw new CliUsageError("Unknown audiences command.");
+}
+async function runNewsletterDomains(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.newsletters.domains.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown newsletter-domains command.");
+}
+async function runNewsletters(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "create") {
+    writeJson(out, await client.newsletters.create(await newsletterCreateParams(parsed.options)));
+    return;
+  }
+  if (subcommand === "update") {
+    const id = requirePositional(parsed.positional, 2, "newsletter id");
+    writeJson(
+      out,
+      await client.newsletters.update(id, await newsletterUpdateParams(parsed.options))
+    );
+    return;
+  }
+  if (subcommand === "preview") {
+    writeJson(
+      out,
+      await client.newsletters.preview(requirePositional(parsed.positional, 2, "newsletter id"))
+    );
+    return;
+  }
+  if (subcommand === "preflight") {
+    writeJson(
+      out,
+      await client.newsletters.preflight(requirePositional(parsed.positional, 2, "newsletter id"))
+    );
+    return;
+  }
+  if (subcommand === "test-send") {
+    writeJson(
+      out,
+      await client.newsletters.sendTest(requirePositional(parsed.positional, 2, "newsletter id"), {
+        recipient_email: getRequiredString(parsed.options, "recipient-email")
+      })
+    );
+    return;
+  }
+  if (subcommand === "schedule") {
+    writeJson(
+      out,
+      await client.newsletters.schedule(requirePositional(parsed.positional, 2, "newsletter id"), {
+        scheduled_at: getRequiredString(parsed.options, "scheduled-at")
+      })
+    );
+    return;
+  }
+  if (subcommand === "cancel") {
+    writeJson(
+      out,
+      await client.newsletters.cancel(requirePositional(parsed.positional, 2, "newsletter id"))
+    );
+    return;
+  }
+  if (subcommand === "resume") {
+    writeJson(
+      out,
+      await client.newsletters.resume(requirePositional(parsed.positional, 2, "newsletter id"))
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown newsletters command.");
+}
+async function runNewsletterAssets(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    const kind = getString(parsed.options, "kind");
+    if (kind !== void 0 && kind !== "image" && kind !== "video") {
+      throw new CliUsageError("--kind must be image or video.");
+    }
+    writeJson(
+      out,
+      await client.newsletters.assets.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit"),
+        kind,
+        q: getString(parsed.options, "q")
+      })
+    );
+    return;
+  }
+  if (subcommand === "upload") {
+    const filePath = requirePositional(parsed.positional, 2, "file");
+    const data = await readFile(realpathSync(filePath));
+    writeJson(
+      out,
+      await client.newsletters.assets.upload({
+        filename: getString(parsed.options, "filename") ?? filePath.split(/[\\/]/).at(-1) ?? "newsletter-asset",
+        data,
+        content_type: getString(parsed.options, "content-type")
+      })
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown newsletter-assets command.");
+}
 function writeError(err, errOut) {
   if (err instanceof CliUsageError) {
     errOut.write(`Error: ${err.message}
@@ -589,9 +964,10 @@ ${JSON.stringify(err.body, null, 2)}
     return;
   }
   if (err instanceof ShipMailError) {
-    const status = err.status !== void 0 ? ` (HTTP ${err.status})` : "";
-    const requestId = err.requestId ? ` request_id=${err.requestId}` : "";
-    errOut.write(`Error: ${err.message}${status}${requestId}
+    const shipmailError = err;
+    const status = shipmailError.status !== void 0 ? ` (HTTP ${shipmailError.status})` : "";
+    const requestId = shipmailError.requestId ? ` request_id=${shipmailError.requestId}` : "";
+    errOut.write(`Error: ${shipmailError.message}${status}${requestId}
 `);
     return;
   }
@@ -633,6 +1009,10 @@ async function runCli(argv, options = {}) {
     else if (command === "messages") await runMessages(client, parsed, out);
     else if (command === "webhooks") await runWebhooks(client, parsed, out);
     else if (command === "suppressions") await runSuppressions(client, parsed, out);
+    else if (command === "newsletters") await runNewsletters(client, parsed, out);
+    else if (command === "newsletter-assets") await runNewsletterAssets(client, parsed, out);
+    else if (command === "newsletter-domains") await runNewsletterDomains(client, parsed, out);
+    else if (command === "audiences") await runAudiences(client, parsed, out);
     else throw new CliUsageError(`Unknown command: ${command}.`);
     return 0;
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipmail-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Official CLI for the ShipMail API",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "shipmail": "0.1.21"
+    "shipmail": "0.1.26"
   },
   "devDependencies": {
     "tsup": "^8.4.0",