npm package: @getplatform/getmailer-cli
Description: CLI for GetMailer - Send transactional emails with ease
Author: GetMailer
Latest version: 1.0.1

# GetMailer CLI

Command-line interface for [GetMailer](https://getmailer.app) - Send transactional emails with ease.

## Installation

```bash
npm install -g getmailer
```

## Quick Start

1. **Get your API key** from [getmailer.app/api-keys](https://getmailer.app/api-keys)

2. **Login with your API key:**
   ```bash
   getmailer login --key gm_your_api_key_here
   ```

3. **Send your first email:**
   ```bash
   getmailer send \
     --from "hello@yourdomain.com" \
     --to "user@example.com" \
     --subject "Hello from GetMailer" \
     --html "<h1>Hello World!</h1>"
   ```

## Commands

### Authentication

```bash
# Login with API key
getmailer login --key <api-key>

# Logout
getmailer logout
```

### Sending Emails

```bash
# Send a simple email
getmailer send \
  -f sender@example.com \
  -t recipient@example.com \
  -s "Subject" \
  --html "<p>Hello!</p>"

# Send with HTML file
getmailer send \
  -f sender@example.com \
  -t recipient@example.com \
  -s "Newsletter" \
  --html-file ./email.html

# Send using a template
getmailer send \
  -f sender@example.com \
  -t recipient@example.com \
  -s "Welcome" \
  --template template_id \
  --vars '{"name": "John"}'

# Send to multiple recipients
getmailer send \
  -f sender@example.com \
  -t user1@example.com user2@example.com \
  -s "Announcement" \
  --html "<p>Important update!</p>"
```

### Batch Emails

```bash
# Create a batch job
getmailer batch create \
  --name "Weekly Newsletter" \
  --from sender@example.com \
  --subject "Weekly Update" \
  --html-file ./newsletter.html \
  --recipients ./recipients.json

# Recipients JSON format:
# [
#   {"to": "user1@example.com", "variables": {"name": "Alice"}},
#   {"to": "user2@example.com", "variables": {"name": "Bob"}}
# ]
```

### Email Management

```bash
# List sent emails
getmailer emails list
getmailer emails list --limit 50

# Get email details
getmailer emails get <email-id>
```

### Templates

```bash
# List templates
getmailer templates list

# Create a template
getmailer templates create \
  --name "Welcome Email" \
  --subject "Welcome, {{name}}!" \
  --html "<h1>Hello {{name}}</h1><p>Welcome to our service!</p>"

# Create from file
getmailer templates create \
  --name "Newsletter" \
  --subject "Weekly Update" \
  --html-file ./template.html

# Update a template
getmailer templates update <template-id> \
  --subject "New Subject"

# Delete a template
getmailer templates delete <template-id>
```

### Domains

```bash
# List domains
getmailer domains list

# Add a domain (returns DNS records to configure)
getmailer domains add example.com

# Check verification status
getmailer domains verify <domain-id>

# Delete a domain
getmailer domains delete <domain-id>
```

### Webhooks

```bash
# List webhooks
getmailer webhooks list

# Create a webhook
getmailer webhooks create \
  --url https://yourapp.com/webhook \
  --events SENT DELIVERED OPENED BOUNCED

# Update a webhook
getmailer webhooks update <webhook-id> \
  --events SENT DELIVERED \
  --disable

# Delete a webhook
getmailer webhooks delete <webhook-id>
```

### Suppression List

```bash
# List suppressed emails
getmailer suppression list

# Add to suppression list
getmailer suppression add --emails bad@example.com spam@example.com

# Add from file
getmailer suppression add --file ./suppressed.txt

# Remove from suppression
getmailer suppression remove --emails user@example.com
```

### Analytics

```bash
# Get summary statistics
getmailer analytics

# Get daily statistics
getmailer analytics --type daily --days 30
```

### API Keys

```bash
# List API keys
getmailer keys list

# Create a new API key
getmailer keys create --name "Production"

# Delete an API key
getmailer keys delete <key-id>
```

### Email Validation

```bash
# Validate a single email
getmailer validate email user@example.com

# Validate emails from a file
getmailer validate list ./emails.txt

# Export results to CSV
getmailer validate list ./emails.txt --output results.csv

# Export as JSON
getmailer validate list ./emails.txt --json --output results.json
```

### A/B Testing (Experiments)

```bash
# List experiments
getmailer experiments list
getmailer ab list  # alias

# Create an experiment
getmailer experiments create

# Get experiment results
getmailer experiments get <experiment-id>

# End an experiment
getmailer experiments end <experiment-id>
getmailer experiments end <experiment-id> --winner <variant-id>
```

### System Monitoring

```bash
# Check system health
getmailer monitor health
getmailer status health  # alias

# View metrics
getmailer monitor metrics

# Live dashboard (updates every 10s)
getmailer monitor dashboard --watch
```

### Inbox Placement Testing

```bash
# Manage seed lists
getmailer inbox-test seeds list
getmailer inbox-test seeds create

# Run inbox placement test
getmailer inbox-test run

# View test results
getmailer inbox-test list
getmailer inbox-test results <test-id>

# Watch for results (polls until complete)
getmailer inbox-test results <test-id> --watch
```

### Auto-Remediation

```bash
# View configured playbooks
getmailer remediation playbooks

# View remediation history
getmailer remediation history
getmailer remediation history --limit 50

# Test a trigger (dry run)
getmailer remediation test BOUNCE_RATE_HIGH
```

### Configuration

```bash
# Set configuration values
getmailer config set apiKey gm_your_key
getmailer config set apiUrl https://custom.getmailer.app

# Get configuration
getmailer config get apiKey

# List all configuration
getmailer config list

# Show config file path
getmailer config path

# Clear all configuration
getmailer config clear
```

## Output Formats

Most commands support `--json` flag for JSON output:

```bash
getmailer emails list --json
getmailer templates list --json
```

## Environment Variables

- `GETMAILER_API_KEY` - API key (alternative to `getmailer login`)
- `GETMAILER_API_URL` - Custom API URL (default: https://getmailer.app)

## Examples

### Send a Welcome Email with Template

```bash
# Create template
getmailer templates create \
  --name "Welcome" \
  --subject "Welcome to {{company}}, {{name}}!" \
  --html "<h1>Hello {{name}}</h1><p>Welcome to {{company}}!</p>"

# Send using template
getmailer send \
  -f welcome@myapp.com \
  -t newuser@example.com \
  -s "Welcome" \
  --template <template-id> \
  --vars '{"name": "John", "company": "Acme Inc"}'
```

### Send Newsletter to Multiple Recipients

```bash
# Create recipients.json
echo '[
  {"to": "alice@example.com", "variables": {"name": "Alice"}},
  {"to": "bob@example.com", "variables": {"name": "Bob"}}
]' > recipients.json

# Send batch
getmailer batch create \
  --name "March Newsletter" \
  --from newsletter@myapp.com \
  --template <template-id> \
  --recipients ./recipients.json
```

## Support

- Documentation: [getmailer.app/docs](https://getmailer.app/docs)
- Issues: [GitHub Issues](https://github.com/getmailer/getmailer/issues)