@sesender/cli

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

npm install -g @sesender/cli

Quick Start

# 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!"

# Send an email
ses-cli email send --to [email protected] --subject "Hello" --body "Welcome!" --from [email protected]

# View analytics
ses-cli analytics

Configuration

The CLI stores configuration in ~/.sesenderrc. You can also use environment variables:

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 at sesender.com
2. Go to Settings → API Keys
3. Create a new API key with the permissions you need

Config Commands

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

Commands

SMS

Send single or bulk SMS messages with provider selection, scheduling, and history.

# 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.

# Send a single email
ses-cli email send --to "[email protected]" --subject "Hello" --body "Welcome!" --from "[email protected]"

# Send HTML email from file
ses-cli email send --to "[email protected]" --subject "Newsletter" --html-file ./template.html --from "[email protected]"

# With provider selection
ses-cli email send --to "[email protected]" --subject "Test" --body "Hello" --provider mailgun

# With click and open tracking
ses-cli email send --to "[email protected]" --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 "[email protected]"

# 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.

# 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.

# 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.

# 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

Templates

List and view your saved message templates.

# 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.

# 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.

# 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.

# 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.

# Validate a phone number
ses-cli validate phone +1234567890

# Validate an email address
ses-cli validate email [email protected]

# 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.

# Check emails (comma-separated)
ses-cli seed-check --emails "[email protected],[email protected]" --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.

# View analytics
ses-cli analytics
ses-cli analytics --period 30d
ses-cli analytics --json

Account

View account information and rate limits.

# Account information
ses-cli account info

# Check API rate limits
ses-cli account rate

Global Options

| Flag | Description | |------|-------------| | --json | Output in JSON format for scripting | | --help | Show help message | | --version | Show version number |

CSV Format

For SMS bulk:

phone
+1234567890
+0987654321

For Email bulk:

email
[email protected]
[email protected]

For Contact import:

name,phone,email,amount,brand
John Doe,+1234567890,[email protected],500,MyCompany
Jane Smith,+0987654321,[email protected],300,MyCompany

Dynamic fields from CSV columns are available as {{First}}, {{Last}}, {{Amount}}, {{Brand}}, {{Custom1}}, {{Custom2}}, {{Custom3}} in message bodies.

Scripting Examples

# 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

# 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 usage:

ses-cli account rate

Links

• Dashboard: sesender.com
• API Docs: sesender.com/api-docs
• Support: [email protected]

License

MIT