shipmail-cli 0.3.0 → 0.4.1

package/README.md

@@ -34,6 +34,7 @@ shipmail mailboxes resume mbx_123
 shipmail mailboxes forwarding-add mbx_123 --destination owner@example.net
 shipmail mailboxes forwarding mbx_123
 shipmail mailboxes forwarding-remove mbx_123 fwd_123
+shipmail mailboxes rules mbx_123
 shipmail mailboxes app-passwords list mbx_123
 shipmail mailboxes app-passwords create mbx_123 --name "Desktop mail" --expires-at 2026-10-01T00:00:00Z
 shipmail mailboxes app-passwords revoke mbx_123 appwd_123
@@ -51,6 +52,30 @@ shipmail messages send \
 shipmail messages list --client-reference crm-123
 shipmail messages reply msg_123 --to user@example.com --text "Thanks"
 
+# Stage a raw file, then pass the returned sat_... ID when sending
+shipmail mailboxes stage-attachment mbx_123 ./invoice.pdf --content-type application/pdf
+
+# Prepare a five-minute, single-use upload URL for a browser-hosted component
+shipmail mailboxes prepare-attachment-upload mbx_123 ./invoice.pdf --content-type application/pdf
+
+shipmail messages send \
+  --mailbox-id mbx_123 \
+  --to customer@example.com \
+  --subject "Invoice" \
+  --text "Attached." \
+  --staged-attachment-id sat_123 \
+  --scheduled-at 2026-08-01T08:00:00.000Z
+
+shipmail scheduled-messages list
+shipmail scheduled-messages get msg_123
+shipmail scheduled-messages update msg_123 \
+  --to customer@example.com \
+  --subject "Updated invoice" \
+  --text "Attached." \
+  --staged-attachment-id sat_123 \
+  --scheduled-at 2026-08-02T08:00:00.000Z
+shipmail scheduled-messages cancel msg_123
+
 # Use an sm_test_... key to simulate an outbound result and fake inbound reply
 shipmail messages send --mailbox-id mbx_123 --to user@example.com --subject "Test" --text "Not delivered" --sandbox-outcome bounced
 shipmail mailboxes sandbox-inbound mbx_123 --from customer@example.com --subject "Re: Test" --text "Fake inbound reply"
@@ -126,10 +151,11 @@ Use repeatable `--header "Name: value"` flags for request headers. Use `--output
 - `status`
 - `api <METHOD> <PATH>`
 - `domains list|search|create|get|verify|delete`
-- `mailboxes list|create|get|suspend|resume|forwarding|forwarding-add|forwarding-remove|app-passwords|folders|identities`
+- `mailboxes list|create|get|suspend|resume|forwarding|forwarding-add|forwarding-remove|app-passwords|folders|identities|stage-attachment|prepare-attachment-upload`
 - `inbox list|message|threads|thread|thread-state|draft|send-draft|reply-message|reply-thread|update|move`
 - `reply-scans create|status|results`
 - `messages send|list|get|reply` (test keys also support `--sandbox-outcome`)
+- `scheduled-messages list|get|update|cancel`
 - `mailboxes sandbox-inbound`
 - `webhooks list|create|test|deliveries|replay-delivery`
 - `suppressions list|remove`

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { createHash } from "crypto";
 import { realpathSync } from "fs";
 import { readFile, writeFile } from "fs/promises";
 import { env as processEnv, exit, stderr, stdout } from "process";
@@ -13,7 +14,7 @@ import {
 } from "shipmail";
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.1";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -178,6 +179,12 @@ function parseArchiveVisibility(options) {
   if (value === "private" || value === "public") return value;
   throw new CliUsageError("--archive-visibility must be private or public.");
 }
+function parseStylingMode(options) {
+  const value = getString(options, "styling-mode");
+  if (value === void 0) return void 0;
+  if (value === "styled" || value === "plain") return value;
+  throw new CliUsageError("--styling-mode must be styled or plain.");
+}
 async function newsletterCreateParams(options) {
   const audience_id = getRequiredString(options, "audience-id");
   const newsletter_domain_id = getRequiredString(options, "newsletter-domain-id");
@@ -194,6 +201,7 @@ async function newsletterCreateParams(options) {
   }
   const send_window_hours = getNumber(options, "send-window-hours");
   const archive_visibility = parseArchiveVisibility(options);
+  const styling_mode = parseStylingMode(options);
   const preview_text = getString(options, "preview-text");
   const from_name = getString(options, "from-name");
   return {
@@ -207,7 +215,8 @@ async function newsletterCreateParams(options) {
     ...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 } : {}
+    ...archive_visibility !== void 0 ? { archive_visibility } : {},
+    ...styling_mode !== void 0 ? { styling_mode } : {}
   };
 }
 async function newsletterUpdateParams(options) {
@@ -219,6 +228,7 @@ async function newsletterUpdateParams(options) {
   const from_name = getString(options, "from-name");
   const send_window_hours = getNumber(options, "send-window-hours");
   const archive_visibility = parseArchiveVisibility(options);
+  const styling_mode = parseStylingMode(options);
   const blocksInput = getString(options, "blocks");
   const bodyHtmlInput = getString(options, "body-html");
   const bodyTextInput = getString(options, "body-text");
@@ -236,7 +246,8 @@ async function newsletterUpdateParams(options) {
     ...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 } : {}
+    ...archive_visibility !== void 0 ? { archive_visibility } : {},
+    ...styling_mode !== void 0 ? { styling_mode } : {}
   };
   if (Object.keys(params).length === 0) {
     throw new CliUsageError("Provide at least one field to update.");
@@ -315,6 +326,7 @@ function usage() {
 
 Usage:
   shipmail status
+  shipmail capabilities
   shipmail api <METHOD> <PATH> [--data JSON|@file] [--output file]
   shipmail domains list [--limit 25] [--cursor cur]
   shipmail domains search <keyword>
@@ -335,9 +347,12 @@ Usage:
   shipmail mailboxes app-passwords revoke <id> <app-password-id>
   shipmail mailboxes folders <id>
   shipmail mailboxes identities <id>
+  shipmail mailboxes rules <id>
   shipmail mailboxes forwarding <id>
   shipmail mailboxes forwarding-add <id> --destination owner@example.com
   shipmail mailboxes forwarding-remove <id> <forwarding-id>
+  shipmail mailboxes prepare-attachment-upload <id> <file> [--filename name] [--content-type type]
+  shipmail mailboxes stage-attachment <id> <file> [--filename name] [--content-type type]
   shipmail mailboxes sandbox-inbound <id> --from sender@example.com --subject "Test" (--text "Hello" | --html "<p>Hello</p>") [--to support@example.com]
   shipmail inbox list <mailbox-id> [--folder-role inbox] [--after ISO] [--before ISO] [--limit 25] [--cursor cur]
   shipmail inbox message <mailbox-id> <message-id>
@@ -354,6 +369,10 @@ Usage:
   shipmail messages list (--mailbox-id mbx | --client-reference crm-123) [--limit 25] [--cursor cur]
   shipmail messages get <message-id>
   shipmail messages reply <message-id> --to user@example.com (--text "Hello" | --html "<p>Hello</p>") [--client-reference crm-reply-123]
+  shipmail scheduled-messages list [--include-held] [--search text] [--limit 100]
+  shipmail scheduled-messages get <message-id>
+  shipmail scheduled-messages update <message-id> --to user@example.com --subject "Hi" --scheduled-at ISO (--text "Hello" | --html "<p>Hello</p>") [--staged-attachment-id sat_...]
+  shipmail scheduled-messages cancel <message-id>
   shipmail reply-scans create --mailbox-id mbx --after ISO [--before ISO]
   shipmail reply-scans status <scan-id>
   shipmail reply-scans results <scan-id> [--limit 25] [--cursor cur]
@@ -367,8 +386,9 @@ Usage:
     --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
+    --blocks @blocks.json \\
+    [--styling-mode styled|plain]
+  shipmail newsletters update nws_789 --subject "Updated subject" --blocks @blocks-v2.json [--styling-mode styled|plain]
   shipmail newsletters preview <id>
   shipmail newsletters preflight <id>
   shipmail newsletters test-send <id> --recipient-email owner@example.com
@@ -419,6 +439,9 @@ Booking page conferencing:
   --conferencing-provider <zoom|google_meet>  Create a meeting for every booking.
   --conferencing-provider none                Stop creating meeting links on update.
 
+Newsletter styling:
+  --styling-mode <styled|plain>  styled applies Shipmail's email theme. plain sends your HTML without injected styles, width, or centering, so the reader's email client styles it.
+
 Global options:
   --api-key <key>       API key. Defaults to SHIPMAIL_API_KEY.
   --base-url <url>      API base URL. Defaults to SHIPMAIL_BASE_URL or ${DEFAULT_BASE_URL}.
@@ -526,6 +549,7 @@ async function sendMessageParams(options) {
     ...metadata ? { metadata } : {},
     ...getString(options, "source-rfc-message-id") ? { source_rfc_message_id: getString(options, "source-rfc-message-id") } : {},
     ...headers.length > 0 ? { headers } : {},
+    ...getStringList(options, "staged-attachment-id").length > 0 ? { staged_attachment_ids: getStringList(options, "staged-attachment-id") } : {},
     ...getString(options, "scheduled-at") ? { scheduled_at: getString(options, "scheduled-at") } : {},
     ...getString(options, "sandbox-outcome") ? {
       sandbox_outcome: getEnum(options, "sandbox-outcome", [
@@ -735,6 +759,13 @@ async function runMailboxes(client, parsed, out) {
     );
     return;
   }
+  if (subcommand === "rules") {
+    writeJson(
+      out,
+      await client.mailboxes.getRules(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
   if (subcommand === "forwarding") {
     writeJson(
       out,
@@ -759,6 +790,35 @@ async function runMailboxes(client, parsed, out) {
     writeJson(out, { ok: true, id: forwardingId });
     return;
   }
+  if (subcommand === "stage-attachment") {
+    const mailboxId = requirePositional(parsed.positional, 2, "mailbox id");
+    const filePath = requirePositional(parsed.positional, 3, "file");
+    const data = await readFile(realpathSync(filePath));
+    writeJson(
+      out,
+      await client.mailboxes.stageAttachment(mailboxId, {
+        filename: getString(parsed.options, "filename") ?? filePath.split(/[\\/]/).at(-1) ?? "attachment",
+        data,
+        content_type: getString(parsed.options, "content-type")
+      })
+    );
+    return;
+  }
+  if (subcommand === "prepare-attachment-upload") {
+    const mailboxId = requirePositional(parsed.positional, 2, "mailbox id");
+    const filePath = requirePositional(parsed.positional, 3, "file");
+    const data = await readFile(realpathSync(filePath));
+    writeJson(
+      out,
+      await client.mailboxes.prepareStagedAttachmentUpload(mailboxId, {
+        filename: getString(parsed.options, "filename") ?? filePath.split(/[\\/]/).at(-1) ?? "attachment",
+        content_type: getString(parsed.options, "content-type") ?? "application/octet-stream",
+        size: data.byteLength,
+        sha256: createHash("sha256").update(data).digest("hex")
+      })
+    );
+    return;
+  }
   if (subcommand === "sandbox-inbound") {
     const text = getString(parsed.options, "text");
     const html = getString(parsed.options, "html");
@@ -1037,6 +1097,52 @@ async function runMessages(client, parsed, out) {
   }
   throw new CliUsageError("Unknown messages command.");
 }
+async function runScheduledMessages(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.scheduledMessages.list({
+        include_held: getBoolean(parsed.options, "include-held"),
+        search: getString(parsed.options, "search"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  const messageId = requirePositional(parsed.positional, 2, "message id");
+  if (subcommand === "get") {
+    writeJson(out, await client.scheduledMessages.get(messageId));
+    return;
+  }
+  if (subcommand === "cancel") {
+    await client.scheduledMessages.cancel(messageId);
+    writeJson(out, { ok: true, id: messageId });
+    return;
+  }
+  if (subcommand === "update") {
+    const to = messageRecipients(parsed.options, "to");
+    const cc = messageRecipients(parsed.options, "cc");
+    const bcc = messageRecipients(parsed.options, "bcc");
+    const text = getString(parsed.options, "text");
+    const html = getString(parsed.options, "html");
+    if (to.length === 0) throw new CliUsageError("Provide at least one --to recipient.");
+    if (!text && !html) throw new CliUsageError("Provide --text or --html.");
+    const update = {
+      to,
+      ...cc.length > 0 ? { cc } : {},
+      ...bcc.length > 0 ? { bcc } : {},
+      subject: getRequiredString(parsed.options, "subject"),
+      ...text ? { text } : {},
+      ...html ? { html } : {},
+      ...getStringList(parsed.options, "staged-attachment-id").length > 0 ? { staged_attachment_ids: getStringList(parsed.options, "staged-attachment-id") } : {},
+      scheduled_at: getRequiredString(parsed.options, "scheduled-at")
+    };
+    writeJson(out, await client.scheduledMessages.update(messageId, update));
+    return;
+  }
+  throw new CliUsageError("Unknown scheduled-messages command.");
+}
 async function runWebhooks(client, parsed, out) {
   const subcommand = parsed.positional[1];
   if (subcommand === "list") {
@@ -1779,6 +1885,18 @@ async function runCli(argv, options = {}) {
       await writeRawResponse(parsed, { stdout: out }, response);
       return 0;
     }
+    if (command === "capabilities") {
+      const response = await rawApiRequest(
+        parsed,
+        options,
+        "GET",
+        "/capabilities",
+        void 0,
+        true
+      );
+      await writeRawResponse(parsed, { stdout: out }, response);
+      return 0;
+    }
     if (command === "api") {
       const method = requirePositional(parsed.positional, 1, "method").toUpperCase();
       const path = apiPath(requirePositional(parsed.positional, 2, "path"));
@@ -1792,6 +1910,7 @@ async function runCli(argv, options = {}) {
     else if (command === "mailboxes") await runMailboxes(client, parsed, out);
     else if (command === "inbox") await runInbox(client, parsed, out);
     else if (command === "messages") await runMessages(client, parsed, out);
+    else if (command === "scheduled-messages") await runScheduledMessages(client, parsed, out);
     else if (command === "reply-scans") await runReplyScans(client, parsed, out);
     else if (command === "webhooks") await runWebhooks(client, parsed, out);
     else if (command === "suppressions") await runSuppressions(client, parsed, out);

package/package.json

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