shipmail-cli 0.6.6 → 0.6.7

package/README.md

@@ -149,6 +149,20 @@ shipmail audiences welcome add-step aud_123 --subject "Welcome" --markdown @welc
 shipmail audiences welcome add-step aud_123 --subject "Our best posts" --markdown @day-3.md --wait-minutes 4320
 shipmail audiences welcome enable aud_123
 
+# Store a template, publish it, then send it by ID
+shipmail templates create \
+  --name "Welcome" \
+  --subject "Welcome, {{name}}" \
+  --html @welcome.html \
+  --fallback plan=Free \
+  --publish
+shipmail templates render tpl_123 --var name=Ada
+shipmail messages send --from hello@example.com --to ada@example.com --template tpl_123 --var name=Ada
+shipmail templates update tpl_123 --subject "Welcome aboard, {{name}}"
+shipmail templates publish tpl_123
+shipmail templates versions tpl_123
+shipmail templates restore tpl_123 1
+
 # Manage webhooks
 shipmail webhooks create \
   --url https://example.com/shipmail/webhook \
@@ -170,6 +184,11 @@ Shipmail converts headings, paragraphs, lists, quotes, code, images, links, divi
 to blocks. A callout starts with a line `:::callout` (optionally `info`, `warning` or `success`,
 then a title) and ends with a line `:::`.
 
+With `messages send --template`, the template supplies the subject and body, so `--subject`,
+`--html` and `--text` are refused. `--var key=value` sets a variable (repeat it; values are text),
+and `--template-version` pins a version instead of the published one. A send missing a required
+variable fails with HTTP 422 and prints each detail with its code, such as `missing_variable`.
+
 `newsletter-assets upload` uses a five-minute direct storage PUT, then calls the single-use
 completion URL. Video uploads require a JPEG poster through `--thumbnail`. `newsletter-assets list`
 includes current newsletter media storage usage and a `pagination.next_cursor` value in the JSON
@@ -191,7 +210,9 @@ Use repeatable `--header "Name: value"` flags for request headers. Use `--output
 - `api <METHOD> <PATH>`
 - `domains list|search|create|get|verify|delete`
 - `mailboxes list|create|get|update|suspend|resume|forwarding|forwarding-add|forwarding-remove|app-passwords|folders|identities|stage-attachment|prepare-attachment-upload`
-- `members list|get`
+- `members list|get|invite`
+- `members invitations list|cancel`
+- `members mailboxes grant|revoke`
 - `inbox list|message|security-review|threads|thread|thread-state|draft|send-draft|reply-message|reply-thread|update|move`
 - `reply-scans create|status|results`
 - `messages send|list|analytics|get|reply` (test keys also support `--sandbox-outcome`)
@@ -199,6 +220,7 @@ Use repeatable `--header "Name: value"` flags for request headers. Use `--output
 - `mailboxes sandbox-inbound`
 - `webhooks list|create|update|test|deliveries|replay-delivery`
 - `suppressions add|list|remove`
+- `templates list|create|get|update|delete|publish|render|versions|version|restore` (`messages send --template` sends one)
 - `audiences list|create|get|update|delete`
 - `audiences feed get|update|rotate|revoke`
 - `audiences welcome get|enable|disable|add-step|update-step|remove-step`
@@ -212,6 +234,15 @@ Member output uses the roles `owner`, `admin`, and `member`. Its `mailbox_access
 `selected`; `mailbox_ids` is empty for `all`, while selected IDs may be limited to mailboxes the
 API key can reach.
 
+`members invite`, `members invitations cancel` and `members mailboxes grant|revoke` need the
+`members:write` permission, which no preset includes. The invitee receives an email and creates
+their own account; the CLI never receives their credentials:
+
+```bash
+shipmail members invite sam@example.com --role member --mailbox mbx_support --newsletter-editor
+shipmail members mailboxes grant mem_sam mbx_sales
+```
+
 Configure a publisher-owned Atom self URL and the number of recent newsletters:
 
 ```bash

package/dist/cli.js

@@ -12,6 +12,7 @@ import {
   ReconciliationRequiredError,
   ShipmailClient,
   ShipmailError,
+  ValidationError,
   WEBHOOK_EVENT_TYPES
 } from "shipmail";
 
@@ -651,7 +652,7 @@ async function login(options) {
 }
 
 // src/version.ts
-var VERSION = "0.6.6";
+var VERSION = "0.6.7";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -774,6 +775,20 @@ function getStringList(options, key) {
   if (isStringArray(value)) return value.flatMap(splitValues);
   return splitValues(value);
 }
+function getKeyValues(options, key) {
+  const value = optionValue(options, key);
+  if (value === void 0) return void 0;
+  const entries = isStringArray(value) ? value : [value];
+  const result = {};
+  for (const entry of entries) {
+    const index = typeof entry === "string" ? entry.indexOf("=") : -1;
+    if (typeof entry !== "string" || index <= 0) {
+      throw new CliUsageError(`--${key} must use key=value format.`);
+    }
+    result[entry.slice(0, index).trim()] = entry.slice(index + 1);
+  }
+  return result;
+}
 function validateBaseUrl(rawValue, allowInsecure) {
   let parsed;
   try {
@@ -1255,6 +1270,11 @@ Usage:
   shipmail mailboxes sandbox-inbound <id> --from sender@example.com --subject "Test" (--text "Hello" | --html "<p>Hello</p>") [--to support@example.com]
   shipmail members list [--limit 25] [--cursor cur]
   shipmail members get <id>
+  shipmail members invitations list
+  shipmail members invite <email> --role admin|member [--all-mailboxes] [--mailbox <mailbox-id> ...] [--newsletter-editor] [--idempotency-key key]
+  shipmail members invitations cancel <invitation-id>
+  shipmail members mailboxes grant <member-id> <mailbox-id>
+  shipmail members mailboxes revoke <member-id> <mailbox-id>
   shipmail inbox list <mailbox-id> [--folder-role inbox] [--search text] [--from text] [--to text] [--subject text] [--has-attachment [true|false]] [--after ISO] [--before ISO] [--limit 25] [--cursor cur]
   shipmail inbox message <mailbox-id> <message-id>
   shipmail inbox security-review <mailbox-id> <message-id> --reason "Reviewed" --expected-content-sha256 HASH
@@ -1268,15 +1288,16 @@ Usage:
   shipmail inbox update-draft <mailbox-id> <thread-id> <draft-id> (--text "Hello" | --html "<p>Hello</p>")  (the new body replaces the old one)
   shipmail inbox delete-draft <mailbox-id> <thread-id> <draft-id>
   shipmail inbox send-draft <mailbox-id> <thread-id> <draft-id> [--expected-content-sha256 hash]
-  shipmail inbox reply-message <mailbox-id> <message-id> --to user@example.com (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false]
-  shipmail inbox reply-thread <mailbox-id> <thread-id> --to user@example.com (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false]
+  shipmail inbox reply-message <mailbox-id> <message-id> --to user@example.com [--cc ...] [--bcc ...] (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false]
+  shipmail inbox reply-thread <mailbox-id> <thread-id> --to user@example.com [--cc ...] [--bcc ...] (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false]
   shipmail inbox update <mailbox-id> <message-id> [--read true] [--starred false]
   shipmail inbox move <mailbox-id> <message-id> (--target-role archive | --target-folder-id fld)
   shipmail messages send (--mailbox-id mbx | --from 'Acme Support <hello@example.com>') --to user@example.com --subject "Hi" --text "Hello" [--track-reply true|false] [--sandbox-outcome delivered|bounced|complained] [--client-reference crm-123] [--metadata JSON|@file] [--source-rfc-message-id '<crm-123@example.com>'] [--header 'X-CRM-ID: 123']
+  shipmail messages send (--mailbox-id mbx | --from hello@example.com) --to user@example.com --template tpl_... [--template-version 2] [--var name=Ada ...]
   shipmail messages list (--mailbox-id mbx | --client-reference crm-123) [--limit 25] [--cursor cur]
   shipmail messages analytics [--updated-after ISO] [--updated-before ISO] [--limit 100] [--cursor cur]
   shipmail messages get <message-id>
-  shipmail messages reply <message-id> --to user@example.com (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false] [--client-reference crm-reply-123]
+  shipmail messages reply <message-id> --to user@example.com [--cc ...] [--bcc ...] (--text "Hello" | --html "<p>Hello</p>") [--track-reply true|false] [--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_...]
@@ -1291,6 +1312,16 @@ Usage:
   shipmail suppressions add <email> [--scope all|marketing]
   shipmail suppressions list [--scope all|marketing] [--limit 25] [--cursor cur]
   shipmail suppressions remove <email>
+  shipmail templates list [--limit 25] [--cursor cur]
+  shipmail templates create --name "Welcome" --subject "Welcome, {{name}}" (--html "<p>Hi {{name}}</p>" | --text "Hi {{name}}") [--fallback name=there ...] [--publish]
+  shipmail templates get <template-id>
+  shipmail templates update <template-id> [--name "..."] [--subject "..."] [--html "..." | --clear-html] [--text "..." | --clear-text] [--fallback key=value ... | --clear-fallbacks]
+  shipmail templates delete <template-id>
+  shipmail templates publish <template-id>
+  shipmail templates render <template-id> [--var name=Ada ...] [--template-version 2]
+  shipmail templates versions <template-id> [--limit 25] [--cursor cur]
+  shipmail templates version <template-id> <version>
+  shipmail templates restore <template-id> <version>
   shipmail newsletters create \\
     --audience-id aud_123 \\
     --sender-identity-id nwsid_456 \\
@@ -1365,6 +1396,17 @@ One-off booking links:
   Revoking a link stops it at once and cannot be undone. Other flags: --description,
   --buffer-minutes, --minimum-notice-minutes, --conferencing-provider, --mailbox.
 
+Templates:
+  {{key}} in the subject, html or text is a variable. --html and --text take the value or @file.
+  --fallback key=value     Default for a variable. Repeat it. A variable without one is required
+                           at send time. On update, the given fallbacks replace all of them.
+  --publish                On create, also publish the draft as version 1.
+  update changes the draft; publish makes it the next version, which sends use. restore copies a
+  version into the draft without publishing it. render previews the draft, or --template-version.
+  messages send --template <id> sends the published version, or --template-version. --var
+  key=value sets a variable (repeat it; values are text). --subject, --html and --text are refused
+  with --template.
+
 Conversation IDs:
   <thread-id> accepts a conversation ID (thd_...) or the mail-server thread ID. Store the
   conversation_id every response carries. thread_id is deprecated and unchanged.
@@ -1373,6 +1415,11 @@ Member access output:
   role is owner, admin, or member. mailbox_access.scope is all or selected. mailbox_ids is empty
   for all; selected IDs may be limited to mailboxes the API key can reach.
 
+Member invitations and mailbox sharing:
+  Needs the members:write permission, which is never granted by default. The invitee receives an
+  email and creates their own account; no credential is returned. Without --all-mailboxes the
+  invitation shares only the --mailbox IDs. --newsletter-editor applies to the member role only.
+
 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.
 
@@ -1580,24 +1627,17 @@ async function sendMessageParams(options) {
   const cc = messageRecipients(options, "cc");
   const bcc = messageRecipients(options, "bcc");
   const replyTo = getString(options, "reply-to");
-  const subject = getRequiredString(options, "subject");
-  const text = getString(options, "text");
-  const html = getString(options, "html");
   const headers = outboundMessageHeaders(options);
   const metadata = await messageMetadata(options);
   if (!mailboxId && !from) throw new CliUsageError("Provide --mailbox-id or --from.");
   if (to.length === 0) throw new CliUsageError("Provide at least one --to recipient.");
-  if (!text && !html) throw new CliUsageError("Provide --text or --html.");
-  return {
+  const common = {
     ...mailboxId ? { mailbox_id: mailboxId } : {},
     ...from ? { from } : {},
     to,
     ...cc.length > 0 ? { cc } : {},
     ...bcc.length > 0 ? { bcc } : {},
     ...replyTo ? { reply_to: replyTo } : {},
-    subject,
-    ...html ? { html } : {},
-    ...text ? { text } : {},
     ...getString(options, "client-reference") ? { client_reference: getString(options, "client-reference") } : {},
     ...metadata ? { metadata } : {},
     ...getString(options, "source-rfc-message-id") ? { source_rfc_message_id: getString(options, "source-rfc-message-id") } : {},
@@ -1616,10 +1656,44 @@ async function sendMessageParams(options) {
       ])
     } : {}
   };
+  const templateId = getString(options, "template");
+  const templateVersion = getNumber(options, "template-version");
+  const variables = getKeyValues(options, "var");
+  if (templateId) {
+    for (const key of ["subject", "html", "text"]) {
+      if (optionValue(options, key) !== void 0) {
+        throw new CliUsageError(
+          `--${key} cannot be used with --template: the template supplies the subject and body.`
+        );
+      }
+    }
+    return {
+      ...common,
+      template: {
+        id: templateId,
+        ...templateVersion !== void 0 ? { version: templateVersion } : {},
+        ...variables ? { variables } : {}
+      }
+    };
+  }
+  if (templateVersion !== void 0 || variables) {
+    throw new CliUsageError("--template-version and --var need --template.");
+  }
+  const subject = getRequiredString(options, "subject");
+  const text = getString(options, "text");
+  const html = getString(options, "html");
+  if (!text && !html) throw new CliUsageError("Provide --text or --html.");
+  return {
+    ...common,
+    subject,
+    ...html ? { html } : {},
+    ...text ? { text } : {}
+  };
 }
 async function replyToMessageParams(options) {
   const to = messageRecipients(options, "to");
   const cc = messageRecipients(options, "cc");
+  const bcc = messageRecipients(options, "bcc");
   const text = getString(options, "text");
   const html = getString(options, "html");
   const headers = outboundMessageHeaders(options);
@@ -1629,6 +1703,7 @@ async function replyToMessageParams(options) {
   return {
     to,
     ...cc.length > 0 ? { cc } : {},
+    ...bcc.length > 0 ? { bcc } : {},
     ...html ? { html } : {},
     ...text ? { text } : {},
     ...getString(options, "client-reference") ? { client_reference: getString(options, "client-reference") } : {},
@@ -2532,6 +2607,45 @@ async function runMembers(client, parsed, out) {
     );
     return;
   }
+  if (subcommand === "invite") {
+    const idempotencyKey = getString(parsed.options, "idempotency-key");
+    writeJson(
+      out,
+      await client.members.invite(
+        inviteMemberParams(parsed),
+        idempotencyKey ? { idempotencyKey } : void 0
+      )
+    );
+    return;
+  }
+  if (subcommand === "invitations") {
+    const command = requirePositional(parsed.positional, 2, "invitations command");
+    if (command === "list") {
+      writeJson(out, await client.members.listInvitations());
+      return;
+    }
+    if (command === "cancel") {
+      const invitationId = requirePositional(parsed.positional, 3, "invitation id");
+      await client.members.cancelInvitation(invitationId);
+      writeJson(out, { ok: true, id: invitationId });
+      return;
+    }
+    throw new CliUsageError("Unknown members invitations command.");
+  }
+  if (subcommand === "mailboxes") {
+    const command = requirePositional(parsed.positional, 2, "mailboxes command");
+    const memberId2 = requirePositional(parsed.positional, 3, "member id");
+    const mailboxId = requirePositional(parsed.positional, 4, "mailbox id");
+    if (command === "grant") {
+      writeJson(out, await client.members.grantMailboxAccess(memberId2, mailboxId));
+      return;
+    }
+    if (command === "revoke") {
+      writeJson(out, await client.members.revokeMailboxAccess(memberId2, mailboxId));
+      return;
+    }
+    throw new CliUsageError("Unknown members mailboxes command.");
+  }
   const memberId = requirePositional(parsed.positional, 2, "member id");
   if (subcommand === "get") {
     writeJson(out, await client.members.get(memberId));
@@ -2539,6 +2653,29 @@ async function runMembers(client, parsed, out) {
   }
   throw new CliUsageError("Unknown members command.");
 }
+var INVITATION_ROLES = ["admin", "member"];
+function inviteMemberParams(parsed) {
+  const email = requirePositional(parsed.positional, 2, "email");
+  const rawRole = getRequiredString(parsed.options, "role");
+  const role = INVITATION_ROLES.find((candidate) => candidate === rawRole);
+  if (!role) throw new CliUsageError("--role must be admin or member.");
+  const allMailboxes = getBoolean(parsed.options, "all-mailboxes") === true;
+  const mailboxIds = getStringList(parsed.options, "mailbox");
+  if (allMailboxes && mailboxIds.length > 0) {
+    throw new CliUsageError("Use either --all-mailboxes or --mailbox, not both.");
+  }
+  const newsletterEditor = getBoolean(parsed.options, "newsletter-editor") === true;
+  if (newsletterEditor && role !== "member") {
+    throw new CliUsageError("--newsletter-editor applies to the member role only.");
+  }
+  return {
+    email,
+    role,
+    ...allMailboxes ? { mailbox_access: "all" } : {},
+    ...mailboxIds.length > 0 ? { mailbox_ids: mailboxIds } : {},
+    ...newsletterEditor ? { newsletter_role: "editor" } : {}
+  };
+}
 var SUPPRESSION_SCOPES = ["all", "marketing"];
 async function runSuppressions(client, parsed, out) {
   const subcommand = parsed.positional[1];
@@ -2572,6 +2709,131 @@ async function runSuppressions(client, parsed, out) {
   }
   throw new CliUsageError("Unknown suppressions command.");
 }
+async function templateCreateParams(options) {
+  const html = await readTextInput(getString(options, "html"));
+  const text = await readTextInput(getString(options, "text"));
+  const fallbacks = getKeyValues(options, "fallback");
+  const publish = getBoolean(options, "publish");
+  if (!html && !text) throw new CliUsageError("Provide --html or --text.");
+  return {
+    name: getRequiredString(options, "name"),
+    subject: getRequiredString(options, "subject"),
+    ...html ? { html } : {},
+    ...text ? { text } : {},
+    ...fallbacks ? { fallbacks } : {},
+    ...publish !== void 0 ? { publish } : {}
+  };
+}
+async function templateBodyUpdate(options, key) {
+  const value = await readTextInput(getString(options, key));
+  const clear = getBoolean(options, `clear-${key}`) === true;
+  if (value !== void 0 && clear) {
+    throw new CliUsageError(`Use either --${key} or --clear-${key}, not both.`);
+  }
+  return clear ? null : value;
+}
+async function templateUpdateParams(options) {
+  const name = getString(options, "name");
+  const subject = getString(options, "subject");
+  const html = await templateBodyUpdate(options, "html");
+  const text = await templateBodyUpdate(options, "text");
+  const fallbacks = getKeyValues(options, "fallback");
+  const clearFallbacks = getBoolean(options, "clear-fallbacks") === true;
+  if (fallbacks && clearFallbacks) {
+    throw new CliUsageError("Use either --fallback or --clear-fallbacks, not both.");
+  }
+  const params = {
+    ...name !== void 0 ? { name } : {},
+    ...subject !== void 0 ? { subject } : {},
+    ...html !== void 0 ? { html } : {},
+    ...text !== void 0 ? { text } : {},
+    ...fallbacks ? { fallbacks } : clearFallbacks ? { fallbacks: {} } : {}
+  };
+  if (name === void 0 && subject === void 0 && html === void 0 && text === void 0 && params.fallbacks === void 0) {
+    throw new CliUsageError("Provide at least one field to change.");
+  }
+  return params;
+}
+function templateVersionPositional(positional) {
+  const raw = requirePositional(positional, 3, "version");
+  const version = Number(raw);
+  if (!Number.isInteger(version) || version < 1) {
+    throw new CliUsageError("Version must be a positive integer.");
+  }
+  return version;
+}
+async function runTemplates(client, parsed, out) {
+  const subcommand = parsed.positional[1];
+  if (subcommand === "list") {
+    writeJson(
+      out,
+      await client.templates.list({
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "create") {
+    writeJson(out, await client.templates.create(await templateCreateParams(parsed.options)));
+    return;
+  }
+  const id = requirePositional(parsed.positional, 2, "template id");
+  if (subcommand === "get") {
+    writeJson(out, await client.templates.get(id));
+    return;
+  }
+  if (subcommand === "update") {
+    writeJson(out, await client.templates.update(id, await templateUpdateParams(parsed.options)));
+    return;
+  }
+  if (subcommand === "delete") {
+    await client.templates.delete(id);
+    writeJson(out, { ok: true, id });
+    return;
+  }
+  if (subcommand === "publish") {
+    writeJson(out, await client.templates.publish(id));
+    return;
+  }
+  if (subcommand === "render") {
+    const variables = getKeyValues(parsed.options, "var");
+    const version = getNumber(parsed.options, "template-version");
+    writeJson(
+      out,
+      await client.templates.render(id, {
+        ...variables ? { variables } : {},
+        ...version !== void 0 ? { version } : {}
+      })
+    );
+    return;
+  }
+  if (subcommand === "versions") {
+    writeJson(
+      out,
+      await client.templates.listVersions(id, {
+        cursor: getString(parsed.options, "cursor"),
+        limit: getNumber(parsed.options, "limit")
+      })
+    );
+    return;
+  }
+  if (subcommand === "version") {
+    writeJson(
+      out,
+      await client.templates.getVersion(id, templateVersionPositional(parsed.positional))
+    );
+    return;
+  }
+  if (subcommand === "restore") {
+    writeJson(
+      out,
+      await client.templates.restoreVersion(id, templateVersionPositional(parsed.positional))
+    );
+    return;
+  }
+  throw new CliUsageError("Unknown templates command.");
+}
 var SUBSCRIBER_STATUS_VALUES = [
   "subscribed",
   "pending",
@@ -3520,6 +3782,13 @@ ${JSON.stringify(err.body, null, 2)}
     const messageId = shipmailError instanceof ReconciliationRequiredError && shipmailError.messageId ? ` message_id=${shipmailError.messageId}` : "";
     errOut.write(`Error: ${shipmailError.message}${status}${requestId}${messageId}
 `);
+    if (shipmailError instanceof ValidationError) {
+      for (const detail of shipmailError.details ?? []) {
+        const code = detail.code ? ` (${detail.code})` : "";
+        errOut.write(`  ${detail.field}: ${detail.message}${code}
+`);
+      }
+    }
     if (shipmailError.actionUrl) {
       const reason = shipmailError.reason ? ` (${shipmailError.reason})` : "";
       errOut.write(`Ask the organization owner to open${reason}: ${shipmailError.actionUrl}
@@ -3603,6 +3872,7 @@ async function runCli(argv, options = {}) {
     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);
+    else if (command === "templates") await runTemplates(client, parsed, out);
     else if (command === "newsletters") await runNewsletters(client, parsed, out);
     else if (command === "newsletter-assets")
       await runNewsletterAssets(client, parsed, out, options.fetch ?? globalThis.fetch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipmail-cli",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Official CLI for the Shipmail API",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "dependencies": {
-    "shipmail": "0.6.7",
+    "shipmail": "0.6.8",
     "zod": "^4.6.5"
   },
   "devDependencies": {