shipmail-cli 0.1.7 → 0.1.9

package/README.md

@@ -22,19 +22,35 @@ You can also pass `--api-key` to any command. Use `SHIPMAIL_BASE_URL` or `--base
 # Check public API health
 shipmail status
 
-# Create a domain and verify DNS
+# Create a domain, retrieve records, and verify DNS
 shipmail domains create example.com
+shipmail domains dns-records dom_123
 shipmail domains verify dom_123
 
 # Create a mailbox
-shipmail mailboxes create --domain-id dom_123 --address hello --display-name "Hello"
+shipmail mailboxes create --domain-id dom_123 --address hello --password-file ./mailbox-password.txt --display-name "Hello"
+shipmail mailboxes suspend mbx_123
+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
 
 # Send email
 shipmail messages send \
   --mailbox-id mbx_123 \
   --to user@example.com \
   --subject "Hello" \
-  --text "It works."
+  --text "It works." \
+  --client-reference crm-123 \
+  --metadata '{"campaign":"onboarding"}' \
+  --source-rfc-message-id '<crm-123@example.com>'
+
+shipmail messages list --client-reference crm-123
+shipmail messages reply msg_123 --to user@example.com --text "Thanks"
+
+# 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"
 
 # Read inbound mail
 shipmail inbox list mbx_123 --folder-role inbox --limit 25
@@ -62,6 +78,7 @@ shipmail webhooks create \
   --url https://example.com/shipmail/webhook \
   --events message.received,message.bounced
 shipmail webhooks deliveries whk_123 --status failed
+shipmail webhooks replay-delivery whk_123 dlv_123 --idempotency-key replay-123
 ```
 
 `newsletter-assets list` includes current newsletter media storage usage in the JSON response.
@@ -87,10 +104,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|folders|identities|rules`
+- `mailboxes list|create|get|suspend|resume|forwarding|forwarding-add|forwarding-remove|folders|identities|rules`
 - `inbox list|thread|update|move`
-- `messages send|list|get`
-- `webhooks list|create|test|deliveries`
+- `messages send|list|get|reply` (test keys also support `--sandbox-outcome`)
+- `mailboxes sandbox-inbound`
+- `webhooks list|create|test|deliveries|replay-delivery`
 - `suppressions list|remove`
 - `newsletter-domains list`
 - `newsletters create|update|preview|preflight|test-send|schedule|cancel|resume`

package/dist/cli.js

@@ -12,7 +12,7 @@ import {
 } from "shipmail";
 
 // src/version.ts
-var VERSION = "0.1.7";
+var VERSION = "0.1.9";
 
 // src/cli.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -311,21 +311,34 @@ Usage:
   shipmail domains search <keyword>
   shipmail domains create <name>
   shipmail domains get <id>
+  shipmail domains dns-records <id>
   shipmail domains verify <id>
   shipmail domains delete <id>
   shipmail mailboxes list [--domain-id dom] [--limit 25] [--cursor cur]
-  shipmail mailboxes create --domain-id dom --address hello [--display-name "Hello"]
+  shipmail mailboxes create --domain-id dom --address hello (--password value | --password-file path) [--display-name "Hello"]
   shipmail mailboxes get <id>
+  shipmail mailboxes suspend <id>
+  shipmail mailboxes resume <id>
+  shipmail mailboxes export <id>
+  shipmail mailboxes export-status <id> <export-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 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] [--limit 25]
   shipmail inbox thread <mailbox-id> <thread-id>
   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 --to user@example.com --subject "Hi" --text "Hello"
+  shipmail messages send --mailbox-id mbx --to user@example.com --subject "Hi" --text "Hello" [--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 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 webhooks list
   shipmail webhooks create --url https://example.com/hook --events message.received,message.bounced
+  shipmail webhooks replay-delivery <webhook-id> <delivery-id> [--idempotency-key key]
   shipmail suppressions list
   shipmail suppressions remove <email>
   shipmail newsletters create \\
@@ -359,7 +372,7 @@ Usage:
   shipmail audiences subscribers resubscribe <audience-id> <subscriber-id> --consent-source "Signup form"
   shipmail audiences subscribers remove <audience-id> <subscriber-id>
   shipmail calendar events list --mailbox hello@example.com --from 2026-08-01T00:00:00Z --to 2026-08-08T00:00:00Z [--expand true] [--limit 100]
-  shipmail calendar events create --mailbox hello@example.com --title "Sync" --start 2026-08-01T14:00:00 [--timezone Europe/Paris] [--duration PT30M] [--all-day true] [--location "HQ"] [--video-url https://...] [--reminders JSON|@file]
+  shipmail calendar events create --mailbox hello@example.com --title "Sync" --start 2026-08-01T14:00:00 [--timezone Europe/Paris] [--duration PT30M] [--attendees JSON|@file] [--reminders JSON|@file]
   shipmail calendar events get <event-id> --mailbox hello@example.com
   shipmail calendar events update <event-id> --mailbox hello@example.com [--title "..."] [--start ...]
   shipmail calendar events delete <event-id> --mailbox hello@example.com
@@ -425,7 +438,24 @@ function webhookDeliveryParams(options) {
     ...eventType ? { event_type: eventType } : {}
   };
 }
-function sendMessageParams(options) {
+function outboundMessageHeaders(options) {
+  const headers = getStringList(options, "header");
+  return headers.map((value) => {
+    const index = value.indexOf(":");
+    if (index <= 0) throw new CliUsageError("--header must use 'Name: value' format.");
+    return { name: value.slice(0, index).trim(), value: value.slice(index + 1).trim() };
+  });
+}
+async function messageMetadata(options) {
+  const raw = getString(options, "metadata");
+  if (!raw) return void 0;
+  const parsed = await readJsonInput(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliUsageError("--metadata must be a JSON object or @path/to/file.json.");
+  }
+  return parsed;
+}
+async function sendMessageParams(options) {
   const mailboxId = getString(options, "mailbox-id");
   const from = getString(options, "from");
   const to = messageRecipients(options, "to");
@@ -435,6 +465,8 @@ function sendMessageParams(options) {
   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.");
@@ -447,7 +479,47 @@ function sendMessageParams(options) {
     ...replyTo ? { reply_to: replyTo } : {},
     subject,
     ...html ? { html } : {},
-    ...text ? { text } : {}
+    ...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") } : {},
+    ...headers.length > 0 ? { headers } : {},
+    ...getString(options, "scheduled-at") ? { scheduled_at: getString(options, "scheduled-at") } : {},
+    ...getString(options, "sandbox-outcome") ? {
+      sandbox_outcome: getEnum(options, "sandbox-outcome", [
+        "delivered",
+        "bounced",
+        "complained"
+      ])
+    } : {}
+  };
+}
+async function replyToMessageParams(options) {
+  const to = messageRecipients(options, "to");
+  const cc = messageRecipients(options, "cc");
+  const text = getString(options, "text");
+  const html = getString(options, "html");
+  const headers = outboundMessageHeaders(options);
+  const metadata = await messageMetadata(options);
+  if (to.length === 0) throw new CliUsageError("Provide at least one --to recipient.");
+  if (!text && !html) throw new CliUsageError("Provide --text or --html.");
+  return {
+    to,
+    ...cc.length > 0 ? { cc } : {},
+    ...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") } : {},
+    ...headers.length > 0 ? { headers } : {},
+    ...getString(options, "scheduled-at") ? { scheduled_at: getString(options, "scheduled-at") } : {},
+    ...getString(options, "sandbox-outcome") ? {
+      sandbox_outcome: getEnum(options, "sandbox-outcome", [
+        "delivered",
+        "bounced",
+        "complained"
+      ])
+    } : {}
   };
 }
 async function runDomains(client, parsed, out) {
@@ -480,6 +552,13 @@ async function runDomains(client, parsed, out) {
     writeJson(out, await client.domains.get(requirePositional(parsed.positional, 2, "domain id")));
     return;
   }
+  if (subcommand === "dns-records") {
+    writeJson(
+      out,
+      await client.domains.getDnsRecords(requirePositional(parsed.positional, 2, "domain id"))
+    );
+    return;
+  }
   if (subcommand === "verify") {
     writeJson(
       out,
@@ -510,11 +589,22 @@ async function runMailboxes(client, parsed, out) {
   }
   if (subcommand === "create") {
     const displayName = getString(parsed.options, "display-name");
+    const passwordValue = getString(parsed.options, "password");
+    const passwordFile = getString(parsed.options, "password-file");
+    if (passwordValue && passwordFile) {
+      throw new CliUsageError("Pass either --password or --password-file, not both.");
+    }
+    if (!passwordValue && !passwordFile) {
+      throw new CliUsageError("Missing --password or --password-file.");
+    }
+    const password = passwordFile ? (await readFile(passwordFile, "utf8")).replace(/\r?\n$/, "") : passwordValue;
+    if (!password) throw new CliUsageError("Mailbox password must not be empty.");
     writeJson(
       out,
       await client.mailboxes.create({
         domain_id: getRequiredString(parsed.options, "domain-id"),
         address: getRequiredString(parsed.options, "address"),
+        password,
         ...displayName ? { display_name: displayName } : {}
       })
     );
@@ -527,6 +617,37 @@ async function runMailboxes(client, parsed, out) {
     );
     return;
   }
+  if (subcommand === "suspend") {
+    writeJson(
+      out,
+      await client.mailboxes.suspend(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "resume") {
+    writeJson(
+      out,
+      await client.mailboxes.resume(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "export") {
+    writeJson(
+      out,
+      await client.mailboxes.createExport(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "export-status") {
+    writeJson(
+      out,
+      await client.mailboxes.getExport(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        requirePositional(parsed.positional, 3, "export id")
+      )
+    );
+    return;
+  }
   if (subcommand === "folders") {
     writeJson(
       out,
@@ -548,6 +669,58 @@ async function runMailboxes(client, parsed, out) {
     );
     return;
   }
+  if (subcommand === "forwarding") {
+    writeJson(
+      out,
+      await client.mailboxes.listForwarding(requirePositional(parsed.positional, 2, "mailbox id"))
+    );
+    return;
+  }
+  if (subcommand === "forwarding-add") {
+    writeJson(
+      out,
+      await client.mailboxes.createForwarding(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        { destination: getRequiredString(parsed.options, "destination") }
+      )
+    );
+    return;
+  }
+  if (subcommand === "forwarding-remove") {
+    const mailboxId = requirePositional(parsed.positional, 2, "mailbox id");
+    const forwardingId = requirePositional(parsed.positional, 3, "forwarding id");
+    await client.mailboxes.deleteForwarding(mailboxId, forwardingId);
+    writeJson(out, { ok: true, id: forwardingId });
+    return;
+  }
+  if (subcommand === "sandbox-inbound") {
+    const text = getString(parsed.options, "text");
+    const html = getString(parsed.options, "html");
+    if (!text && !html) throw new CliUsageError("Provide --text or --html.");
+    const to = messageRecipients(parsed.options, "to");
+    const cc = messageRecipients(parsed.options, "cc");
+    const headers = outboundMessageHeaders(parsed.options);
+    writeJson(
+      out,
+      await client.mailboxes.injectSandboxInbound(
+        requirePositional(parsed.positional, 2, "mailbox id"),
+        {
+          from: getRequiredString(parsed.options, "from"),
+          ...to.length > 0 ? { to } : {},
+          ...cc.length > 0 ? { cc } : {},
+          subject: getRequiredString(parsed.options, "subject"),
+          ...text ? { text } : {},
+          ...html ? { html } : {},
+          ...getString(parsed.options, "message-id") ? { message_id: getString(parsed.options, "message-id") } : {},
+          ...getString(parsed.options, "in-reply-to") ? { in_reply_to: getString(parsed.options, "in-reply-to") } : {},
+          ...getStringList(parsed.options, "reference").length > 0 ? { references: getStringList(parsed.options, "reference") } : {},
+          ...getString(parsed.options, "received-at") ? { received_at: getString(parsed.options, "received-at") } : {},
+          ...headers.length > 0 ? { headers } : {}
+        }
+      )
+    );
+    return;
+  }
   throw new CliUsageError("Unknown mailboxes command.");
 }
 async function runInbox(client, parsed, out) {
@@ -616,20 +789,36 @@ async function runInbox(client, parsed, out) {
 async function runMessages(client, parsed, out) {
   const subcommand = parsed.positional[1];
   if (subcommand === "send") {
-    writeJson(out, await client.messages.send(sendMessageParams(parsed.options)));
+    writeJson(out, await client.messages.send(await sendMessageParams(parsed.options)));
     return;
   }
   if (subcommand === "list") {
+    const mailboxId = getString(parsed.options, "mailbox-id");
+    const clientReference = getString(parsed.options, "client-reference");
+    if (!mailboxId && !clientReference) {
+      throw new CliUsageError("Provide --mailbox-id or --client-reference.");
+    }
+    const filter = mailboxId ? { mailbox_id: mailboxId, ...clientReference ? { client_reference: clientReference } : {} } : { client_reference: clientReference };
     writeJson(
       out,
       await client.messages.list({
-        mailbox_id: getRequiredString(parsed.options, "mailbox-id"),
+        ...filter,
         cursor: getString(parsed.options, "cursor"),
         limit: getNumber(parsed.options, "limit")
       })
     );
     return;
   }
+  if (subcommand === "reply") {
+    writeJson(
+      out,
+      await client.messages.reply(
+        requirePositional(parsed.positional, 2, "message id"),
+        await replyToMessageParams(parsed.options)
+      )
+    );
+    return;
+  }
   if (subcommand === "get") {
     writeJson(
       out,
@@ -680,6 +869,18 @@ async function runWebhooks(client, parsed, out) {
     );
     return;
   }
+  if (subcommand === "replay-delivery") {
+    const idempotencyKey = getString(parsed.options, "idempotency-key");
+    writeJson(
+      out,
+      await client.webhooks.replayDelivery(
+        requirePositional(parsed.positional, 2, "webhook id"),
+        requirePositional(parsed.positional, 3, "delivery id"),
+        idempotencyKey ? { idempotencyKey } : void 0
+      )
+    );
+    return;
+  }
   throw new CliUsageError("Unknown webhooks command.");
 }
 async function runSuppressions(client, parsed, out) {
@@ -704,6 +905,7 @@ async function runSuppressions(client, parsed, out) {
 }
 var SUBSCRIBER_STATUS_VALUES = [
   "subscribed",
+  "pending",
   "unsubscribed",
   "bounced",
   "complained",
@@ -1033,6 +1235,22 @@ async function readRemindersInput(value) {
   }
   return parsed;
 }
+function isAttendeeArray(value) {
+  return Array.isArray(value) && value.every((item) => {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) return false;
+    const email = Reflect.get(item, "email");
+    const name = Reflect.get(item, "name");
+    return typeof email === "string" && (name === void 0 || typeof name === "string");
+  });
+}
+async function readAttendeesInput(value) {
+  const parsed = await readJsonInput(value);
+  if (parsed === void 0) return void 0;
+  if (!isAttendeeArray(parsed)) {
+    throw new CliUsageError("--attendees must be a JSON array of { email, name? } objects.");
+  }
+  return parsed;
+}
 async function calendarEventFields(options) {
   const description = getString(options, "description");
   const timezone = getString(options, "timezone");
@@ -1045,6 +1263,7 @@ async function calendarEventFields(options) {
   const freeBusyStatus = getEnum(options, "free-busy-status", CALENDAR_FREE_BUSY_STATUSES);
   const privacy = getEnum(options, "privacy", CALENDAR_PRIVACIES);
   const reminders = await readRemindersInput(getString(options, "reminders"));
+  const attendees = await readAttendeesInput(getString(options, "attendees"));
   return {
     ...description !== void 0 ? { description } : {},
     ...timezone !== void 0 ? { timezone } : {},
@@ -1056,7 +1275,8 @@ async function calendarEventFields(options) {
     ...status !== void 0 ? { status } : {},
     ...freeBusyStatus !== void 0 ? { free_busy_status: freeBusyStatus } : {},
     ...privacy !== void 0 ? { privacy } : {},
-    ...reminders !== void 0 ? { reminders } : {}
+    ...reminders !== void 0 ? { reminders } : {},
+    ...attendees !== void 0 ? { attendees } : {}
   };
 }
 async function runCalendarEvents(client, parsed, out) {

package/package.json

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