@sesender/cli 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# @sesender/cli
+
+The official SESender command-line tool. Send SMS/emails, manage contacts, view analytics, and control campaigns directly from your terminal.
+
+## Installation
+
+```bash
+npm install -g @sesender/cli
+```
+
+## Quick Start
+
+```bash
+# Configure your API key
+ses-cli config set --api-key YOUR_API_KEY --base-url https://sesender.com
+
+# Send an SMS
+ses-cli sms send --to +1234567890 --body "Hello from SESender CLI!"
+
+# Send an email
+ses-cli email send --to user@example.com --subject "Hello" --body "Welcome!"
+
+# View analytics
+ses-cli analytics
+```
+
+## Configuration
+
+The CLI stores configuration in `~/.sesenderrc`. You can also use environment variables:
+
+```bash
+export SES_API_KEY=your_api_key_here
+export SES_BASE_URL=https://sesender.com
+```
+
+### Get your API key
+
+1. Log in to your SESender dashboard
+2. Go to **Settings > API Keys**
+3. Create a new API key with the permissions you need
+
+## Commands
+
+### Config
+
+```bash
+ses-cli config set --api-key KEY --base-url URL   # Save configuration
+ses-cli config show                                # Show current config
+ses-cli config clear                               # Remove saved config
+```
+
+### SMS
+
+```bash
+ses-cli sms send --to PHONE --body MESSAGE [--from SENDER_ID]
+ses-cli sms bulk --file contacts.csv --body MESSAGE [--from SENDER_ID]
+ses-cli sms history [--limit 20] [--page 1]
+```
+
+### Email
+
+```bash
+ses-cli email send --to EMAIL --subject SUBJECT --body TEXT [--html file.html] [--from SENDER]
+ses-cli email bulk --file contacts.csv --subject SUBJECT --body TEXT [--html file.html]
+ses-cli email history [--limit 20] [--page 1]
+```
+
+### Contacts
+
+```bash
+ses-cli contacts list [--limit 20] [--page 1] [--group GROUP_NAME]
+ses-cli contacts import --file contacts.csv [--group GROUP_NAME]
+ses-cli contacts groups
+```
+
+### Campaigns & Analytics
+
+```bash
+ses-cli campaigns list [--limit 20]
+ses-cli analytics [--json]
+```
+
+### Validation
+
+```bash
+ses-cli validate phone --phone +1234567890
+ses-cli validate email --email user@example.com
+```
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output in JSON format for scripting |
+| `--help` | Show help message |
+| `--version` | Show version number |
+
+## CSV Format
+
+### For SMS bulk:
+```csv
+phone
++1234567890
++0987654321
+```
+
+### For Email bulk:
+```csv
+email
+user1@example.com
+user2@example.com
+```
+
+### For Contact import:
+```csv
+name,phone,email
+John Doe,+1234567890,john@example.com
+Jane Smith,+0987654321,jane@example.com
+```
+
+## Scripting Examples
+
+```bash
+# Send SMS to a list and get JSON output
+ses-cli sms bulk --file numbers.csv --body "Flash sale!" --json > result.json
+
+# Check if a phone is valid in a script
+if ses-cli validate phone +1234567890 --json | grep -q '"valid":true'; then
+  echo "Phone is valid"
+fi
+
+# Export analytics to file
+ses-cli analytics --json > analytics_$(date +%Y%m%d).json
+```
+
+## Rate Limits
+
+The CLI respects the same rate limits as your API key. Check your current limits:
+
+```bash
+ses-cli analytics --json | grep rateLimit
+```
+
+## License
+
+MIT

package/bin/ses-cli.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+import { configSet, configShow, configClear } from "../src/commands/config.mjs";
+import { smsSend, smsBulk, smsHistory } from "../src/commands/sms.mjs";
+import { emailSend, emailBulk, emailHistory } from "../src/commands/email.mjs";
+import { contactsList, contactsImport, contactsGroups } from "../src/commands/contacts.mjs";
+import { campaignsList, analyticsOverview } from "../src/commands/campaigns.mjs";
+import { validatePhone, validateEmail } from "../src/commands/validate.mjs";
+
+const VERSION = "1.0.0";
+
+function parseArgs(argv) {
+  const args = { _positional: [] };
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i].startsWith("--")) {
+      const key = argv[i];
+      if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+        args[key] = argv[i + 1];
+        i += 2;
+      } else {
+        args[key] = true;
+        i++;
+      }
+    } else {
+      args._positional.push(argv[i]);
+      i++;
+    }
+  }
+  return args;
+}
+
+function showHelp() {
+  console.log(`
+SESender CLI v${VERSION}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+USAGE
+  ses-cli <command> <subcommand> [options]
+
+COMMANDS
+  config set     Configure API key and base URL
+  config show    Show current configuration
+  config clear   Remove saved configuration
+
+  sms send       Send a single SMS
+  sms bulk       Send bulk SMS from CSV file
+  sms history    View SMS message history
+
+  email send     Send a single email
+  email bulk     Send bulk emails from CSV file
+  email history  View email message history
+
+  contacts list    List contacts
+  contacts import  Import contacts from CSV
+  contacts groups  List contact groups
+
+  campaigns list   List campaigns with stats
+  analytics        View analytics overview
+
+  validate phone   Validate a phone number
+  validate email   Validate an email address
+
+GLOBAL OPTIONS
+  --json         Output in JSON format (machine-readable)
+  --help         Show this help message
+  --version      Show version number
+
+EXAMPLES
+  ses-cli config set --api-key sk_live_abc123 --base-url https://sesender.com
+  ses-cli sms send --to +1234567890 --body "Hello from CLI!"
+  ses-cli email send --to user@example.com --subject "Test" --body "Hello"
+  ses-cli sms bulk --file numbers.csv --body "Promo: 20% off!"
+  ses-cli contacts import --file contacts.csv --group "Newsletter"
+  ses-cli validate phone +1234567890
+  ses-cli analytics --json
+
+ENVIRONMENT VARIABLES
+  SES_API_KEY     API key (overrides config file)
+  SES_BASE_URL    Base URL (overrides config file)
+
+CONFIGURATION
+  Config file: ~/.sesenderrc
+  Create API keys at: Settings > API Keys in your SESender dashboard
+`);
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+
+  if (rawArgs.length === 0 || rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    showHelp();
+    return;
+  }
+
+  if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
+    console.log(`ses-cli v${VERSION}`);
+    return;
+  }
+
+  const command = rawArgs[0];
+  const subcommand = rawArgs[1] && !rawArgs[1].startsWith("--") ? rawArgs[1] : null;
+  const argsStart = subcommand ? 2 : 1;
+  const args = parseArgs(rawArgs.slice(argsStart));
+  const jsonMode = rawArgs.includes("--json");
+
+  try {
+    switch (command) {
+      case "config":
+        switch (subcommand) {
+          case "set": configSet(args); break;
+          case "show": configShow(); break;
+          case "clear": configClear(); break;
+          default:
+            console.error("Usage: ses-cli config <set|show|clear>");
+            process.exit(1);
+        }
+        break;
+
+      case "sms":
+        switch (subcommand) {
+          case "send": await smsSend(args, jsonMode); break;
+          case "bulk": await smsBulk(args, jsonMode); break;
+          case "history": await smsHistory(args, jsonMode); break;
+          default:
+            console.error("Usage: ses-cli sms <send|bulk|history>");
+            process.exit(1);
+        }
+        break;
+
+      case "email":
+        switch (subcommand) {
+          case "send": await emailSend(args, jsonMode); break;
+          case "bulk": await emailBulk(args, jsonMode); break;
+          case "history": await emailHistory(args, jsonMode); break;
+          default:
+            console.error("Usage: ses-cli email <send|bulk|history>");
+            process.exit(1);
+        }
+        break;
+
+      case "contacts":
+        switch (subcommand) {
+          case "list": await contactsList(args, jsonMode); break;
+          case "import": await contactsImport(args, jsonMode); break;
+          case "groups": await contactsGroups(args, jsonMode); break;
+          default:
+            console.error("Usage: ses-cli contacts <list|import|groups>");
+            process.exit(1);
+        }
+        break;
+
+      case "campaigns":
+        switch (subcommand) {
+          case "list": await campaignsList(args, jsonMode); break;
+          default:
+            console.error("Usage: ses-cli campaigns <list>");
+            process.exit(1);
+        }
+        break;
+
+      case "analytics":
+        await analyticsOverview(args, jsonMode);
+        break;
+
+      case "validate":
+        switch (subcommand) {
+          case "phone": await validatePhone(args, jsonMode); break;
+          case "email": await validateEmail(args, jsonMode); break;
+          default:
+            console.error("Usage: ses-cli validate <phone|email>");
+            process.exit(1);
+        }
+        break;
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error("Run 'ses-cli --help' for usage information.");
+        process.exit(1);
+    }
+  } catch (error) {
+    if (error.message !== "process.exit") {
+      console.error(`Unexpected error: ${error.message}`);
+      process.exit(1);
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@sesender/cli",
+  "version": "1.0.0",
+  "description": "SESender CLI - Send SMS/emails, manage contacts, and view analytics from your terminal",
+  "type": "module",
+  "bin": {
+    "ses-cli": "./bin/ses-cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": ["sesender", "sms", "email", "marketing", "cli", "bulk-sms", "bulk-email"],
+  "author": "SESender Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sesender/cli"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {}
+}

package/src/api.mjs

@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const CONFIG_PATH = join(homedir(), ".sesenderrc");
+
+export function getConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export function getApiKey() {
+  return process.env.SES_API_KEY || getConfig().apiKey;
+}
+
+export function getBaseUrl() {
+  return process.env.SES_BASE_URL || getConfig().baseUrl || "https://sesender.com";
+}
+
+export async function apiRequest(method, path, body = null, queryParams = null) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error("Error: No API key configured.");
+    console.error("Run: ses-cli config set --api-key YOUR_KEY");
+    console.error("Or set the SES_API_KEY environment variable.");
+    process.exit(1);
+  }
+
+  const baseUrl = getBaseUrl();
+  let url = `${baseUrl}/api/v1${path}`;
+
+  if (queryParams) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+      if (value !== undefined && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const options = {
+    method,
+    headers: {
+      "X-API-Key": apiKey,
+      "Content-Type": "application/json",
+    },
+  };
+
+  if (body && method !== "GET") {
+    options.body = JSON.stringify(body);
+  }
+
+  try {
+    const response = await fetch(url, options);
+    const data = await response.json();
+
+    if (!response.ok) {
+      if (data.error) {
+        console.error(`Error (${response.status}): ${data.error}`);
+        if (data.details) console.error("Details:", data.details);
+      } else {
+        console.error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+      process.exit(1);
+    }
+
+    return data;
+  } catch (error) {
+    if (error.code === "ECONNREFUSED" || error.code === "ENOTFOUND") {
+      console.error(`Error: Cannot connect to ${baseUrl}`);
+      console.error("Check your base URL with: ses-cli config show");
+    } else {
+      console.error(`Request failed: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/campaigns.mjs

@@ -0,0 +1,69 @@
+import { apiRequest } from "../api.mjs";
+import { formatTable, outputResult, success } from "../output.mjs";
+
+export async function campaignsList(args, jsonMode) {
+  const limit = args["--limit"] || "20";
+  const result = await apiRequest("GET", "/analytics/campaigns", null, { limit });
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    const campaigns = result.campaigns || result.data || [];
+    if (campaigns.length === 0) {
+      console.log("No campaigns found.");
+      return;
+    }
+    formatTable(
+      ["ID", "Name", "Type", "Status", "Sent", "Opens", "Clicks"],
+      campaigns.map((c) => [
+        c.id || c.campaignId,
+        (c.name || c.campaignName || "").slice(0, 25),
+        c.type || "email",
+        c.status || "-",
+        c.sent || c.totalSent || 0,
+        c.opens || c.totalOpens || 0,
+        c.clicks || c.totalClicks || 0,
+      ])
+    );
+    console.log(`\nShowing ${campaigns.length} campaigns`);
+  }
+}
+
+export async function analyticsOverview(args, jsonMode) {
+  const result = await apiRequest("GET", "/analytics/overview");
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    console.log("═══════════════════════════════════════");
+    console.log("         SESender Analytics Overview");
+    console.log("═══════════════════════════════════════");
+    console.log("");
+
+    if (result.sms) {
+      console.log("  SMS:");
+      console.log(`    Total Sent:     ${result.sms.totalSent || 0}`);
+      console.log(`    Delivered:      ${result.sms.delivered || 0}`);
+      console.log(`    Failed:         ${result.sms.failed || 0}`);
+      console.log("");
+    }
+
+    if (result.email) {
+      console.log("  Email:");
+      console.log(`    Total Sent:     ${result.email.totalSent || 0}`);
+      console.log(`    Opens:          ${result.email.totalOpens || 0}`);
+      console.log(`    Clicks:         ${result.email.totalClicks || 0}`);
+      console.log(`    Bounces:        ${result.email.bounces || 0}`);
+      console.log("");
+    }
+
+    if (result.contacts) {
+      console.log("  Contacts:");
+      console.log(`    Total:          ${result.contacts.total || 0}`);
+      console.log(`    Groups:         ${result.contacts.groups || 0}`);
+      console.log("");
+    }
+
+    console.log("═══════════════════════════════════════");
+  }
+}

package/src/commands/config.mjs

@@ -0,0 +1,36 @@
+import { getConfig, saveConfig } from "../api.mjs";
+import { success, info } from "../output.mjs";
+
+export function configSet(args) {
+  const config = getConfig();
+
+  if (args["--api-key"]) {
+    config.apiKey = args["--api-key"];
+    success("API key saved");
+  }
+  if (args["--base-url"]) {
+    config.baseUrl = args["--base-url"];
+    success(`Base URL set to: ${config.baseUrl}`);
+  }
+
+  saveConfig(config);
+}
+
+export function configShow() {
+  const config = getConfig();
+  if (!config.apiKey && !config.baseUrl) {
+    info("No configuration found. Run: ses-cli config set --api-key YOUR_KEY");
+    return;
+  }
+  console.log("Current configuration:");
+  if (config.apiKey) {
+    const masked = config.apiKey.slice(0, 8) + "..." + config.apiKey.slice(-4);
+    console.log(`  API Key: ${masked}`);
+  }
+  console.log(`  Base URL: ${config.baseUrl || "https://sesender.com (default)"}`);
+}
+
+export function configClear() {
+  saveConfig({});
+  success("Configuration cleared");
+}

package/src/commands/contacts.mjs

@@ -0,0 +1,96 @@
+import { readFileSync } from "fs";
+import { apiRequest } from "../api.mjs";
+import { formatTable, outputResult, success } from "../output.mjs";
+
+export async function contactsList(args, jsonMode) {
+  const limit = args["--limit"] || "20";
+  const page = args["--page"] || "1";
+  const group = args["--group"];
+
+  const params = { limit, page };
+  if (group) params.group = group;
+
+  const result = await apiRequest("GET", "/contacts", null, params);
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    const contacts = result.contacts || result.data || [];
+    if (contacts.length === 0) {
+      console.log("No contacts found.");
+      return;
+    }
+    formatTable(
+      ["Name", "Phone", "Email", "Groups"],
+      contacts.map((c) => [
+        c.name || c.firstName || "-",
+        c.phone || "-",
+        c.email || "-",
+        (c.groups || []).join(", ") || "-",
+      ])
+    );
+    console.log(`\nShowing ${contacts.length} contacts (page ${page})`);
+    if (result.total) console.log(`Total: ${result.total}`);
+  }
+}
+
+export async function contactsImport(args, jsonMode) {
+  const file = args["--file"];
+  const group = args["--group"];
+
+  if (!file) {
+    console.error("Usage: ses-cli contacts import --file contacts.csv [--group GROUP_NAME]");
+    console.error("\nCSV format: name,phone,email (first row as headers)");
+    process.exit(1);
+  }
+
+  const csvContent = readFileSync(file, "utf-8");
+  const lines = csvContent.trim().split("\n");
+
+  if (lines.length < 2) {
+    console.error("Error: CSV file must have a header row and at least one data row");
+    process.exit(1);
+  }
+
+  const headers = lines[0].split(",").map((h) => h.trim().toLowerCase());
+  const contacts = lines.slice(1).map((line) => {
+    const values = line.split(",").map((v) => v.trim());
+    const contact = {};
+    headers.forEach((h, i) => {
+      if (values[i]) contact[h] = values[i];
+    });
+    return contact;
+  });
+
+  const payload = { contacts };
+  if (group) payload.group = group;
+
+  const result = await apiRequest("POST", "/contacts/bulk", payload);
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    success(`Import complete: ${result.imported || result.created || contacts.length} contacts imported`);
+    if (result.duplicates) console.log(`  Duplicates skipped: ${result.duplicates}`);
+    if (result.errors) console.log(`  Errors: ${result.errors}`);
+    if (group) console.log(`  Assigned to group: ${group}`);
+  }
+}
+
+export async function contactsGroups(args, jsonMode) {
+  const result = await apiRequest("GET", "/contacts/groups");
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    const groups = result.groups || result.data || [];
+    if (groups.length === 0) {
+      console.log("No contact groups found.");
+      return;
+    }
+    formatTable(
+      ["ID", "Name", "Contacts"],
+      groups.map((g) => [g.id, g.name, g.contactCount || g.count || "-"])
+    );
+  }
+}

package/src/commands/email.mjs

@@ -0,0 +1,117 @@
+import { readFileSync } from "fs";
+import { apiRequest } from "../api.mjs";
+import { formatTable, outputResult, success } from "../output.mjs";
+
+export async function emailSend(args, jsonMode) {
+  const to = args["--to"];
+  const subject = args["--subject"];
+  const body = args["--body"];
+  const html = args["--html"];
+  const from = args["--from"];
+
+  if (!to || !subject || (!body && !html)) {
+    console.error("Usage: ses-cli email send --to EMAIL --subject SUBJECT --body TEXT [--html FILE] [--from SENDER]");
+    process.exit(1);
+  }
+
+  const payload = { to, subject };
+  if (from) payload.from = from;
+
+  if (html) {
+    payload.html = readFileSync(html, "utf-8");
+  } else {
+    payload.body = body;
+  }
+
+  const result = await apiRequest("POST", "/email/send", payload);
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    success(`Email sent to ${to}`);
+    if (result.messageId) console.log(`  Message ID: ${result.messageId}`);
+  }
+}
+
+export async function emailBulk(args, jsonMode) {
+  const file = args["--file"];
+  const subject = args["--subject"];
+  const body = args["--body"];
+  const html = args["--html"];
+  const from = args["--from"];
+
+  if (!file || !subject || (!body && !html)) {
+    console.error("Usage: ses-cli email bulk --file contacts.csv --subject SUBJECT --body TEXT [--html FILE] [--from SENDER]");
+    console.error("\nCSV format: email (one email per line, or column header 'email')");
+    process.exit(1);
+  }
+
+  const csvContent = readFileSync(file, "utf-8");
+  const lines = csvContent.trim().split("\n");
+  const hasHeader = lines[0].toLowerCase().includes("email");
+  const emails = (hasHeader ? lines.slice(1) : lines)
+    .map((l) => l.trim().split(",")[0].trim())
+    .filter(Boolean);
+
+  if (emails.length === 0) {
+    console.error("Error: No email addresses found in CSV file");
+    process.exit(1);
+  }
+
+  const htmlContent = html ? readFileSync(html, "utf-8") : null;
+  console.log(`Sending to ${emails.length} recipients...`);
+
+  let sent = 0;
+  let failed = 0;
+  const errors = [];
+
+  for (const email of emails) {
+    try {
+      const payload = { to: email, subject };
+      if (from) payload.from = from;
+      if (htmlContent) payload.html = htmlContent;
+      else payload.body = body;
+      await apiRequest("POST", "/email/send", payload);
+      sent++;
+    } catch {
+      failed++;
+      errors.push(email);
+    }
+  }
+
+  if (jsonMode) {
+    outputResult({ sent, failed, total: emails.length, errors }, true);
+  } else {
+    success(`Bulk email complete: ${sent} sent, ${failed} failed out of ${emails.length}`);
+    if (errors.length > 0) {
+      console.log(`  Failed emails: ${errors.slice(0, 5).join(", ")}${errors.length > 5 ? "..." : ""}`);
+    }
+  }
+}
+
+export async function emailHistory(args, jsonMode) {
+  const limit = args["--limit"] || "20";
+  const page = args["--page"] || "1";
+
+  const result = await apiRequest("GET", "/email/history", null, { limit, page });
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    const messages = result.messages || result.data || [];
+    if (messages.length === 0) {
+      console.log("No email messages found.");
+      return;
+    }
+    formatTable(
+      ["To", "Subject", "Status", "Date"],
+      messages.map((m) => [
+        m.to || m.recipient,
+        (m.subject || "").slice(0, 30),
+        m.status || "sent",
+        new Date(m.createdAt || m.sentAt).toLocaleString(),
+      ])
+    );
+    console.log(`\nShowing ${messages.length} messages (page ${page})`);
+  }
+}

package/src/commands/sms.mjs

@@ -0,0 +1,105 @@
+import { readFileSync } from "fs";
+import { apiRequest } from "../api.mjs";
+import { formatTable, outputResult, success } from "../output.mjs";
+
+export async function smsSend(args, jsonMode) {
+  const to = args["--to"];
+  const body = args["--body"];
+  const from = args["--from"];
+
+  if (!to || !body) {
+    console.error("Usage: ses-cli sms send --to PHONE --body MESSAGE [--from SENDER_ID]");
+    process.exit(1);
+  }
+
+  const payload = { to, body };
+  if (from) payload.from = from;
+
+  const result = await apiRequest("POST", "/sms/send", payload);
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    success(`SMS sent to ${to}`);
+    if (result.messageId) console.log(`  Message ID: ${result.messageId}`);
+    if (result.cost) console.log(`  Cost: $${result.cost}`);
+  }
+}
+
+export async function smsBulk(args, jsonMode) {
+  const file = args["--file"];
+  const body = args["--body"];
+  const from = args["--from"];
+
+  if (!file) {
+    console.error("Usage: ses-cli sms bulk --file contacts.csv --body MESSAGE [--from SENDER_ID]");
+    console.error("\nCSV format: phone (one number per line, or column header 'phone')");
+    process.exit(1);
+  }
+
+  const csvContent = readFileSync(file, "utf-8");
+  const lines = csvContent.trim().split("\n");
+  const hasHeader = lines[0].toLowerCase().includes("phone");
+  const numbers = (hasHeader ? lines.slice(1) : lines)
+    .map((l) => l.trim().split(",")[0].trim())
+    .filter(Boolean);
+
+  if (numbers.length === 0) {
+    console.error("Error: No phone numbers found in CSV file");
+    process.exit(1);
+  }
+
+  console.log(`Sending to ${numbers.length} recipients...`);
+
+  let sent = 0;
+  let failed = 0;
+  const errors = [];
+
+  for (const phone of numbers) {
+    try {
+      const payload = { to: phone, body };
+      if (from) payload.from = from;
+      await apiRequest("POST", "/sms/send", payload);
+      sent++;
+    } catch {
+      failed++;
+      errors.push(phone);
+    }
+  }
+
+  if (jsonMode) {
+    outputResult({ sent, failed, total: numbers.length, errors }, true);
+  } else {
+    success(`Bulk SMS complete: ${sent} sent, ${failed} failed out of ${numbers.length}`);
+    if (errors.length > 0) {
+      console.log(`  Failed numbers: ${errors.slice(0, 5).join(", ")}${errors.length > 5 ? "..." : ""}`);
+    }
+  }
+}
+
+export async function smsHistory(args, jsonMode) {
+  const limit = args["--limit"] || "20";
+  const page = args["--page"] || "1";
+
+  const result = await apiRequest("GET", "/sms/history", null, { limit, page });
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    const messages = result.messages || result.data || [];
+    if (messages.length === 0) {
+      console.log("No SMS messages found.");
+      return;
+    }
+    formatTable(
+      ["To", "Status", "Date", "Body"],
+      messages.map((m) => [
+        m.to || m.recipient,
+        m.status || "sent",
+        new Date(m.createdAt || m.sentAt).toLocaleString(),
+        (m.body || m.message || "").slice(0, 40),
+      ])
+    );
+    console.log(`\nShowing ${messages.length} messages (page ${page})`);
+  }
+}

package/src/commands/validate.mjs

@@ -0,0 +1,47 @@
+import { apiRequest } from "../api.mjs";
+import { outputResult, success } from "../output.mjs";
+
+export async function validatePhone(args, jsonMode) {
+  const phone = args["--phone"] || args._positional?.[0];
+
+  if (!phone) {
+    console.error("Usage: ses-cli validate phone --phone PHONE_NUMBER");
+    console.error("   or: ses-cli validate phone +1234567890");
+    process.exit(1);
+  }
+
+  const result = await apiRequest("POST", "/validate/phone", { phone });
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    console.log(`Phone: ${phone}`);
+    console.log(`  Valid:    ${result.valid ? "✓ Yes" : "✗ No"}`);
+    if (result.carrier) console.log(`  Carrier:  ${result.carrier}`);
+    if (result.type) console.log(`  Type:     ${result.type}`);
+    if (result.country) console.log(`  Country:  ${result.country}`);
+    if (result.formatted) console.log(`  Format:   ${result.formatted}`);
+  }
+}
+
+export async function validateEmail(args, jsonMode) {
+  const email = args["--email"] || args._positional?.[0];
+
+  if (!email) {
+    console.error("Usage: ses-cli validate email --email ADDRESS");
+    console.error("   or: ses-cli validate email user@example.com");
+    process.exit(1);
+  }
+
+  const result = await apiRequest("POST", "/validate/email", { email });
+
+  if (jsonMode) {
+    outputResult(result, true);
+  } else {
+    console.log(`Email: ${email}`);
+    console.log(`  Valid:       ${result.valid ? "✓ Yes" : "✗ No"}`);
+    if (result.disposable !== undefined) console.log(`  Disposable:  ${result.disposable ? "⚠ Yes" : "No"}`);
+    if (result.mx) console.log(`  MX Record:   ${result.mx}`);
+    if (result.reason) console.log(`  Reason:      ${result.reason}`);
+  }
+}

package/src/output.mjs

@@ -0,0 +1,38 @@
+export function formatTable(headers, rows) {
+  const colWidths = headers.map((h, i) => {
+    const maxRow = rows.reduce((max, row) => Math.max(max, String(row[i] ?? "").length), 0);
+    return Math.max(h.length, maxRow);
+  });
+
+  const separator = colWidths.map((w) => "─".repeat(w + 2)).join("┼");
+  const headerLine = headers.map((h, i) => ` ${h.padEnd(colWidths[i])} `).join("│");
+  const dataLines = rows.map((row) =>
+    row.map((cell, i) => ` ${String(cell ?? "").padEnd(colWidths[i])} `).join("│")
+  );
+
+  console.log(headerLine);
+  console.log(separator);
+  dataLines.forEach((line) => console.log(line));
+}
+
+export function outputResult(data, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(data, null, 2));
+  } else if (typeof data === "string") {
+    console.log(data);
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+export function success(message) {
+  console.log(`✓ ${message}`);
+}
+
+export function info(message) {
+  console.log(`ℹ ${message}`);
+}
+
+export function warn(message) {
+  console.log(`⚠ ${message}`);
+}