@sesender/cli 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,8 @@
 # @sesender/cli
 
-The official SESender command-line tool. Send SMS/emails, manage contacts, view analytics, and control campaigns directly from your terminal.
+The official SESender command-line tool. Send SMS and emails, manage contacts, campaigns, providers, templates, webhooks, tracking domains, and more — directly from your terminal.
+
+Perfect for **developers**, **DevOps engineers**, and **power users** who want to automate messaging workflows, integrate with CI/CD pipelines, or manage their SESender account without opening a browser.
 
 ## Installation
 
@@ -14,11 +16,14 @@ npm install -g @sesender/cli
 # Configure your API key
 ses-cli config set --api-key YOUR_API_KEY --base-url https://sesender.com
 
+# Verify connection
+ses-cli account info
+
 # Send an SMS
-ses-cli sms send --to +1234567890 --body "Hello from SESender CLI!"
+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!"
+ses-cli email send --to user@example.com --subject "Hello" --body "Welcome!" --from sender@yourdomain.com
 
 # View analytics
 ses-cli analytics
@@ -35,13 +40,11 @@ export SES_BASE_URL=https://sesender.com
 
 ### Get your API key
 
-1. Log in to your SESender dashboard
-2. Go to **Settings > API Keys**
+1. Log in to your SESender dashboard at [sesender.com](https://sesender.com)
+2. Go to **Settings → API Keys**
 3. Create a new API key with the permissions you need
 
-## Commands
-
-### Config
+### Config Commands
 
 ```bash
 ses-cli config set --api-key KEY --base-url URL   # Save configuration
@@ -49,44 +52,322 @@ ses-cli config show                                # Show current config
 ses-cli config clear                               # Remove saved config
 ```
 
+---
+
+## Commands
+
 ### SMS
 
+Send single or bulk SMS messages with provider selection, scheduling, and history.
+
 ```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]
+# Send a single SMS
+ses-cli sms send --to "+1234567890" --body "Hello!" --from "MyBrand"
+
+# Send with specific provider
+ses-cli sms send --to "+1234567890" --body "VIP offer" --provider 5 --route PREMIUM
+
+# Schedule an SMS for later
+ses-cli sms send --to "+1234567890" --body "Reminder!" --schedule "2026-06-15T09:00:00Z"
+
+# Bulk SMS from CSV file
+ses-cli sms bulk --file contacts.csv --body "Hi {{First}}, your code is {{Custom1}}" --from "MyBrand"
+
+# View SMS history
+ses-cli sms history --limit 20 --status delivered
 ```
 
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--to` | Recipient phone number (E.164 format) |
+| `--body` | Message text (supports `{{dynamic}}` fields) |
+| `--from` | Sender ID / caller ID |
+| `--provider` | Provider ID to use (from `providers list`) |
+| `--route` | Route name (e.g., DEFAULT, PREMIUM) |
+| `--schedule` | ISO 8601 datetime to schedule the send |
+| `--file` | CSV file for bulk sending |
+
+---
+
 ### Email
 
+Send single or bulk emails with HTML support, provider selection, click/open tracking, and scheduling.
+
+```bash
+# Send a single email
+ses-cli email send --to "user@example.com" --subject "Hello" --body "Welcome!" --from "sender@yourdomain.com"
+
+# Send HTML email from file
+ses-cli email send --to "user@example.com" --subject "Newsletter" --html-file ./template.html --from "news@yourdomain.com"
+
+# With provider selection
+ses-cli email send --to "user@example.com" --subject "Test" --body "Hello" --provider mailgun
+
+# With click and open tracking
+ses-cli email send --to "user@example.com" --subject "Promo" --html-file promo.html --track-clicks --track-opens
+
+# Bulk email from CSV
+ses-cli email bulk --file contacts.csv --subject "Hi {{First}}" --html-file ./template.html --from "sender@yourdomain.com"
+
+# View email history
+ses-cli email history --limit 20 --status delivered
+```
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--to` | Recipient email address |
+| `--subject` | Email subject line |
+| `--body` | Plain text body |
+| `--html` | Inline HTML body |
+| `--html-file` | Path to HTML file for email body |
+| `--from` | Sender email address |
+| `--provider` | Provider name (e.g., sendgrid, mailgun) |
+| `--track-clicks` | Enable click tracking |
+| `--track-opens` | Enable open tracking |
+| `--schedule` | ISO 8601 datetime to schedule the send |
+| `--file` | CSV file for bulk sending |
+
+---
+
+### Providers
+
+List your configured SMS and email providers. Use the provider ID with `--provider` when sending.
+
+```bash
+# List all providers
+ses-cli providers list
+
+# Filter by type
+ses-cli providers list --type sms
+ses-cli providers list --type email
+
+# JSON output for scripting
+ses-cli providers list --json
+```
+
+**Example Output:**
+
+```
+┌────┬─────────────────────┬───────┬────────────┬────────┐
+│ ID │ Name                │ Type  │ Provider   │ Active │
+├────┼─────────────────────┼───────┼────────────┼────────┤
+│ 1  │ Main SMS Route      │ sms   │ TextBack   │ ✓      │
+│ 2  │ Backup SMS          │ sms   │ SMSEdge    │ ✓      │
+│ 3  │ Email Primary       │ email │ SendGrid   │ ✓      │
+│ 4  │ Email Backup        │ email │ Mailjet    │ ✓      │
+└────┴─────────────────────┴───────┴────────────┴────────┘
+```
+
+---
+
+### Campaigns
+
+List, view, pause, resume, and cancel campaigns.
+
 ```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]
+# List campaigns
+ses-cli campaigns list
+ses-cli campaigns list --status sending --type email
+ses-cli campaigns list --limit 50
+
+# View campaign statistics
+ses-cli campaigns stats --id c-abc123
+ses-cli campaigns stats --id mv-campaign-456 --json
+
+# Pause a running campaign
+ses-cli campaigns pause --id c-abc123
+
+# Resume a paused campaign
+ses-cli campaigns resume --id c-abc123
+
+# Cancel a campaign
+ses-cli campaigns cancel --id c-abc123
 ```
 
+---
+
 ### Contacts
 
+Manage contacts and contact groups: list, import, export, and delete.
+
 ```bash
-ses-cli contacts list [--limit 20] [--page 1] [--group GROUP_NAME]
-ses-cli contacts import --file contacts.csv [--group GROUP_NAME]
+# List contacts
+ses-cli contacts list --limit 50
+ses-cli contacts list --search "gmail" --group "VIP"
+
+# Import contacts from CSV
+ses-cli contacts import --file contacts.csv --group "New Leads"
+
+# Export contacts to CSV
+ses-cli contacts export --group "VIP" --output vip-contacts.csv
+
+# List contact groups
 ses-cli contacts groups
+
+# Delete a contact
+ses-cli contacts delete --id 12345
 ```
 
-### Campaigns & Analytics
+---
+
+### Templates
+
+List and view your saved message templates.
 
 ```bash
-ses-cli campaigns list [--limit 20]
-ses-cli analytics [--json]
+# List all templates
+ses-cli templates list
+
+# Filter by type
+ses-cli templates list --type email
+ses-cli templates list --type sms
+
+# View a specific template
+ses-cli templates get --id 42
 ```
 
+---
+
+### Webhooks
+
+Manage webhook endpoints for real-time event notifications.
+
+```bash
+# List webhooks
+ses-cli webhooks list
+
+# Create a webhook
+ses-cli webhooks create --url https://myapp.com/webhook --events "email.delivered,email.bounced"
+
+# Test a webhook (sends test payload)
+ses-cli webhooks test --id wh-123
+
+# Delete a webhook
+ses-cli webhooks delete --id wh-123
+```
+
+**Available Events:**
+
+| Event | Description |
+|-------|-------------|
+| `email.sent` | Email was sent to the provider |
+| `email.delivered` | Email was delivered to recipient |
+| `email.bounced` | Email bounced (hard or soft) |
+| `email.complained` | Recipient marked email as spam |
+| `email.opened` | Email was opened by recipient |
+| `sms.sent` | SMS was sent to the provider |
+| `sms.delivered` | SMS was delivered to recipient |
+| `sms.failed` | SMS delivery failed |
+| `link.clicked` | Tracked link was clicked |
+
+---
+
+### Tracking Domains
+
+View your tracking domains and their click/open statistics.
+
+```bash
+# List tracking domains
+ses-cli tracking list
+
+# View tracking statistics
+ses-cli tracking stats
+ses-cli tracking stats --period 7d
+ses-cli tracking stats --domain track.mydomain.com --period 30d
+```
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--domain` | Filter stats by specific domain |
+| `--period` | Time period: 7d, 30d, 90d (default: 7d) |
+
+---
+
+### Scheduling
+
+View and manage scheduled messages.
+
+```bash
+# List all scheduled messages
+ses-cli schedule list
+
+# Filter by status
+ses-cli schedule list --status pending
+
+# Cancel a scheduled message before it sends
+ses-cli schedule cancel --id sch-123
+```
+
+---
+
 ### Validation
 
+Validate phone numbers and email addresses.
+
 ```bash
-ses-cli validate phone --phone +1234567890
-ses-cli validate email --email user@example.com
+# Validate a phone number
+ses-cli validate phone +1234567890
+
+# Validate an email address
+ses-cli validate email user@example.com
+
+# Bulk validation from file
+ses-cli validate bulk --file emails.csv --type email
+ses-cli validate bulk --file phones.csv --type phone
 ```
 
+---
+
+### Seed Check
+
+Check email lists against seed words and the SES risky email database.
+
+```bash
+# Check emails (comma-separated)
+ses-cli seed-check --emails "user@test.com,info@trap.com" --words "trap,seed,monitor"
+
+# Check emails from CSV file
+ses-cli seed-check --file emails.csv --words "trap,seed"
+
+# Check your seed credit balance
+ses-cli seed-balance
+```
+
+---
+
+### Analytics
+
+View your sending analytics overview.
+
+```bash
+# View analytics
+ses-cli analytics
+ses-cli analytics --period 30d
+ses-cli analytics --json
+```
+
+---
+
+### Account
+
+View account information and rate limits.
+
+```bash
+# Account information
+ses-cli account info
+
+# Check API rate limits
+ses-cli account rate
+```
+
+---
+
 ## Global Options
 
 | Flag | Description |
@@ -95,6 +376,8 @@ ses-cli validate email --email user@example.com
 | `--help` | Show help message |
 | `--version` | Show version number |
 
+---
+
 ## CSV Format
 
 ### For SMS bulk:
@@ -113,11 +396,15 @@ user2@example.com
 
 ### For Contact import:
 ```csv
-name,phone,email
-John Doe,+1234567890,john@example.com
-Jane Smith,+0987654321,jane@example.com
+name,phone,email,amount,brand
+John Doe,+1234567890,john@example.com,500,MyCompany
+Jane Smith,+0987654321,jane@example.com,300,MyCompany
 ```
 
+Dynamic fields from CSV columns are available as `{{First}}`, `{{Last}}`, `{{Amount}}`, `{{Brand}}`, `{{Custom1}}`, `{{Custom2}}`, `{{Custom3}}` in message bodies.
+
+---
+
 ## Scripting Examples
 
 ```bash
@@ -131,16 +418,35 @@ fi
 
 # Export analytics to file
 ses-cli analytics --json > analytics_$(date +%Y%m%d).json
+
+# List all active providers and pipe to jq
+ses-cli providers list --json | jq '.[] | select(.active == true)'
+
+# Monitor campaign progress
+watch -n 5 'ses-cli campaigns stats --id c-abc123 --json'
+
+# Automated seed check from CI/CD
+ses-cli seed-check --file new-subscribers.csv --words "trap,seed,abuse" --json > seed-results.json
 ```
 
+---
+
 ## Rate Limits
 
-The CLI respects the same rate limits as your API key. Check your current limits:
+The CLI respects the same rate limits as your API key. Check your current usage:
 
 ```bash
-ses-cli analytics --json | grep rateLimit
+ses-cli account rate
 ```
 
+---
+
+## Links
+
+- **Dashboard:** [sesender.com](https://sesender.com)
+- **API Docs:** [sesender.com/api-docs](https://sesender.com/api-docs)
+- **Support:** support@sesender.com
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sesender/cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "SESender CLI - Send SMS/emails, manage contacts, and view analytics from your terminal",
   "type": "module",
   "bin": {
@@ -11,7 +11,15 @@
     "src/",
     "README.md"
   ],
-  "keywords": ["sesender", "sms", "email", "marketing", "cli", "bulk-sms", "bulk-email"],
+  "keywords": [
+    "sesender",
+    "sms",
+    "email",
+    "marketing",
+    "cli",
+    "bulk-sms",
+    "bulk-email"
+  ],
   "author": "SESender Team",
   "license": "MIT",
   "repository": {