shipmail-cli 0.3.0 → 0.4.0

package/README.md

@@ -51,6 +51,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 +150,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.0";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -315,6 +316,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>
@@ -338,6 +340,8 @@ Usage:
   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 +358,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]
@@ -526,6 +534,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", [
@@ -759,6 +768,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 +1075,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 +1863,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 +1888,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.0",
   "description": "Official CLI for the ShipMail API",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "shipmail": "0.3.0"
+    "shipmail": "0.4.1"
   },
   "devDependencies": {
     "tsup": "^8.4.0",