Senddy CLI

Official command-line interface for Senddy.io. Send and inspect emails, manage domains, suppressions, inbound routes, webhooks, recipient lists, and billing, all from the command line.

Installation

Requires Node.js 18.13+.

npm install -g senddy-cli

This installs the senddy binary on your PATH.

Authentication

The CLI needs an API key for every command. It's resolved in this order:

1. --key <key> flag
2. SENDDY_API_KEY environment variable
3. ~/.senddyrc config file (set via senddy config set-key)

The most common setup is to store the key once:

senddy config set-key senddy_live_your_api_key

The file is written with 0600 permissions. Use senddy config show to see the currently active key (masked) and which source it came from.

Global flags

| Flag | Description | | ------------- | ----------------------------------------------- | | --key <key> | API key (overrides env and config file) | | --json | Output as JSON instead of human-readable tables | | --no-color | Disable colored output | | --help | Show help for any command | | --version | Print CLI version |

Emails

# Send an email (at least one of --html / --text is required)
senddy emails send \
  --from [email protected] \
  --to [email protected] \
  --subject "Hello" \
  --html "<p>Hi there</p>"

# Attach a downloadable file (base64 + content_type inferred from the extension)
senddy emails send --from [email protected] --to [email protected] --subject "Invoice" \
  --html "<p>See attached.</p>" --attach ./invoice.pdf

# Embed an image inline — reference it in the HTML as cid:FILENAME.
# The derived cid: ref (special chars → "-") is printed after sending.
senddy emails send --from [email protected] --to [email protected] --subject "Welcome" \
  --html '<img src="cid:logo.png">' --inline ./logo.png

# Or send from a JSON file (full SendEmailParams shape)
senddy emails send --file payload.json

# Or pipe JSON via stdin
cat payload.json | senddy emails send --stdin

# Inspect a sent email
senddy emails get email_abc123

# List recent emails (filter by status, sender, recipient, date range)
senddy emails list --limit 25 --status delivered --since 2026-01-01T00:00:00Z

# Fetch the rendered HTML/text body
senddy emails content email_abc123

# Download the raw EML
senddy emails download email_abc123 -o message.eml

# Resend an existing email
senddy emails resend email_abc123

Suppressions

senddy suppressions list --reason hard_bounce --search example.com
senddy suppressions add [email protected]
senddy suppressions remove [email protected]

# Export the full list (CSV by default, or --format json); -o writes to a file
senddy suppressions export --format csv -o suppressions.csv

Domains

# Add a sending domain (prints the verification TXT record to add to DNS)
senddy domains add mail.example.com

# Add a subdomain under a verified root domain
senddy domains add-subdomain <domain-id> mail

# Trigger DNS verification after adding the record
senddy domains verify <domain-id>

# List, inspect, delete
senddy domains list
senddy domains get <domain-id>
senddy domains remove <domain-id>

# Rotate DKIM keys
senddy domains regenerate-dkim <domain-id>

# Bulk DNS health check across all domains
senddy domains dns-health

Inbound Routes

# Create a catchall route forwarding to your webhook
senddy inbound-routes create --match-type catchall --webhook-url https://your-app.example.com/inbound

# List, inspect, update, delete
senddy inbound-routes list
senddy inbound-routes get <route-id>
senddy inbound-routes update <route-id> --enabled false
senddy inbound-routes delete <route-id>

# Verify the MX record points at Senddy
senddy inbound-routes verify-mx <route-id>

Inbound Emails

senddy inbound-emails list --route-id 42 --limit 50
senddy inbound-emails get inbound_xyz

Webhook Endpoints

# Register an endpoint (saves the signing secret on first create).
# --event-type is one of: sent, delivered, bounced, complained, opened, clicked, or '*'.
senddy webhooks create \
  --url https://your-app.example.com/webhooks/senddy \
  --domain mail.example.com \
  --event-type delivered

# List, update, delete, test
senddy webhooks list
senddy webhooks update <id> --url https://new-url.example.com
senddy webhooks delete <id>
senddy webhooks test <id>

# Inspect delivery history
senddy webhooks deliveries <id> --limit 50

Recipient Lists

# Create a list (repeat --pattern for multiple), then list/update/remove
senddy recipient-lists create Internal --pattern "*@example.com"
senddy recipient-lists list
senddy recipient-lists update <id> --name Renamed --pattern "*@example.com"
senddy recipient-lists remove <id>

Billing

# Reads
senddy billing balance
senddy billing history --type deduction --limit 50
senddy billing payments
senddy billing usage --days 30
senddy billing tier
senddy billing auto-refill

# Writes
senddy billing checkout 10000
senddy billing set-auto-refill --enable --threshold 1000 --amount-cents 2000
senddy billing set-auto-refill --disable
senddy billing set-tier pro

Config

senddy config set-key senddy_live_your_api_key
senddy config show

JSON output

Add --json to any command to get machine-readable output instead of tables:

senddy emails list --json | jq '.data[].id'
senddy domains dns-health --json | jq '.data[] | select(.dkim_verified == false)'

In --json mode, failures are emitted as a structured envelope on stderr (stdout stays reserved for successful output) and the process exits non-zero:

{
  "error": {
    "type": "ValidationError",
    "message": "Invalid request",
    "code": "validation_error",
    "status_code": 400,
    "request_id": "req_abc123",
    "details": [{ "field": "to", "message": "required" }]
  }
}

code, status_code, request_id, details (validation), and retry_after (rate limits) are included when present. Check the exit code, then parse stderr for the envelope.

Help

Every command and subcommand supports --help:

senddy --help
senddy emails --help
senddy emails send --help

Behavior

The CLI is built on the Node SDK and inherits its transport behavior: transient failures (429/5xx) are retried with backoff, and emails send is retry-safe (each send carries an auto-generated idempotency key, so a retried send is never delivered twice).

Coverage

The CLI wraps the full public API surface: emails (incl. resend), suppressions (incl. export), domains (incl. add-subdomain), inbound routes/emails, webhooks, recipient lists, and billing (reads + writes: checkout, set-auto-refill, set-tier). Run senddy <command> --help for the full flag list.

Requirements

• Node.js >= 18.13.0
• A Senddy.io API key

License

MIT