CLI Tool

Manage your Postject account, send emails, and monitor delivery from the command line.

Installation

bash

npm install -g postject-cli
# or
yarn global add postject-cli
# or
pnpm add -g postject-cli

Verify installation:

bash

postject --version

Setup

Initialize the CLI with your API key:

bash

postject init

This will prompt for your API key and save configuration to ~/.postject/config.json.

Commands

Send Email

bash

postject send \
  --to user@example.com \
  --subject "Welcome!" \
  --body "<h1>Welcome to our platform</h1>"

Options: --from, --template, --vars, --stream

View Logs

bash

# View specific message
postject logs --message msg_abc123

# Tail logs in real-time
postject logs --stream stream_xyz --tail

Analytics

bash

postject analytics --server srv_abc123

Shows total sent, delivery rate, bounce rate, and average latency.

Manage Servers

bash

# List servers
postject servers list

# Create server
postject servers create "Production Server"

# Delete server
postject servers delete srv_abc123

Manage Streams

bash

# List streams
postject streams list srv_abc123

# Create stream
postject streams create srv_abc123 "Transactional" \
  --slug transactional \
  --type transactional

# Delete stream
postject streams delete srv_abc123 stream_xyz

Manage Templates

bash

# List templates
postject templates list srv_abc123

# Create from file
postject templates create srv_abc123 "Welcome Email" \
  --subject "Welcome!" \
  --file ./templates/welcome.html

# Delete template
postject templates delete srv_abc123 tpl_xyz

Manage Webhooks

bash

# Create webhook
postject webhooks create stream_xyz https://app.com/webhook \
  --events delivered bounced

# Test webhook
postject webhooks test wh_abc123

# View delivery logs
postject webhooks logs wh_abc123 --limit 50

# Delete webhook
postject webhooks delete stream_xyz wh_abc123

Export/Import Config

bash

# Export to YAML
postject export --output config.yaml

# Import configuration
postject import config.yaml

Environment Variables

Override config file with environment variables:

bash

export POSTJECT_API_KEY=pk_live_your_key
export POSTJECT_BASE_URL=https://api.postject.com

postject send --to user@example.com --subject "Test" --body "<p>Test</p>"

Common Workflows

Send Welcome Email

bash

postject send \
  --to newuser@example.com \
  --template tpl_welcome \
  --vars '{"name":"John Doe","company":"Acme Inc"}'

Monitor Message Delivery

bash

# Send email
MSG_ID=$(postject send \
  --to user@example.com \
  --subject "Test" \
  --body "<p>Test</p>" | grep "Message ID" | cut -d: -f2)

# Check status
postject logs --message $MSG_ID

Batch Create Servers

bash

for env in "Production" "Staging" "Development"; do
  postject servers create "$env Server"
done

Backup Configuration

bash

# Export all configuration
postject export --format yaml --output backup.yaml

# Later, restore it
postject import backup.yaml

Shell Completions

Enable tab completion for your shell:

bash

# Bash
postject completion bash > /etc/bash_completion.d/postject

# Zsh
postject completion zsh > /usr/local/share/zsh/site-functions/_postject

# Fish
postject completion fish > ~/.config/fish/completions/postject.fish

Error Handling

The CLI provides clear error messages with suggestions:

bash

$ postject send --to invalid@
✗ Validation error: Invalid email address

$ postject logs --message msg_notfound
✗ Resource not found: Message not found

$ postject send --to user@example.com
✗ API key not configured. Run "postject init" first.

Getting Help

View help for any command:

bash

postject --help
postject send --help
postject webhooks --help