postject-cli

v1.0.2

Published

a month ago

Official CLI for Postject email API

0High
0Medium
0Low

ohfega

postject cli email api smtp transactional email-api

Postject CLI

Official command-line interface for the Postject email API.

Installation

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

Quick Start

# Initialize configuration
postject init

# Send an email
postject send \
  --to [email protected] \
  --subject "Hello" \
  --body "<p>Test email</p>"

# View analytics
postject analytics --server <server_id>

Commands

`postject init`

Initialize CLI configuration (API key, base URL).

postject init

Interactive prompts will ask for:

API Key: Your Postject API key (pk_live_...)
Base URL: API endpoint (default: https://api.postject.com)

Configuration is saved to ~/.postject/config.json.

`postject send`

Send an email.

Options:

-to, --to <email> - Recipient email address (required)
-s, --subject <subject> - Email subject (required)
-b, --body <html> - Email HTML body (required unless using template)
-t, --template <id> - Template ID
-v, --vars <json> - Template variables as JSON
--stream <id> - Stream ID
-f, --from <email> - Sender email (optional if identity configured)

Examples:

# Simple email
postject send \
  --to [email protected] \
  --subject "Welcome!" \
  --body "<h1>Welcome to our platform</h1>"

# Using a template
postject send \
  --to [email protected] \
  --template tpl_abc123 \
  --vars '{"name":"John","order":"12345"}'

# With specific stream
postject send \
  --to [email protected] \
  --subject "Order Confirmation" \
  --body "<p>Your order has been confirmed</p>" \
  --stream stream_xyz789

`postject logs`

View email delivery logs.

Options:

-m, --message <id> - Show specific message details
-s, --stream <id> - Filter by stream ID
-l, --limit <number> - Number of logs to fetch (default: 20)
--tail - Follow logs in real-time
--status <status> - Filter by status (queued|sent|delivered|bounced)

Examples:

# View specific message
postject logs --message msg_abc123

# Tail logs (real-time)
postject logs --stream stream_xyz789 --tail

# List recent messages
postject logs --stream stream_xyz789 --limit 50

`postject analytics`

View server analytics and statistics.

Options:

-s, --server <id> - Server ID (required)
--period <days> - Period in days (default: 30)

Example:

postject analytics --server srv_abc123

# Output:
# 📊 Server Analytics
#
# Total Sent:      15,432
# Delivery Rate:   98.76%
# Bounce Rate:     1.24%
# Avg Latency:     145ms

`postject servers`

Manage servers.

Sub-commands:

`servers list`

List all servers.

postject servers list

`servers create <name>`

Create a new server.

postject servers create "Production Server"

`servers delete <id>`

Delete a server.

postject servers delete srv_abc123

`postject streams`

Manage message streams.

Sub-commands:

`streams list <serverId>`

List all streams for a server.

postject streams list srv_abc123

`streams create <serverId> <name>`

Create a new stream.

Options:

--slug <slug> - Stream slug
--type <type> - Stream type (default: transactional)

postject streams create srv_abc123 "Transactional Emails" \
  --slug transactional \
  --type transactional

`streams delete <serverId> <streamId>`

Delete a stream.

postject streams delete srv_abc123 stream_xyz789

`postject templates`

Manage email templates.

Sub-commands:

`templates list <serverId>`

List all templates.

postject templates list srv_abc123

`templates create <serverId> <name>`

Create a new template.

Options:

-s, --subject <subject> - Email subject
-b, --body <html> - Email HTML body
--file <path> - Path to HTML file

# Inline HTML
postject templates create srv_abc123 "Welcome Email" \
  --subject "Welcome to {{company}}!" \
  --body "<h1>Welcome {{name}}!</h1>"

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

`templates delete <serverId> <templateId>`

Delete a template.

postject templates delete srv_abc123 tpl_abc123

`postject webhooks`

Manage webhooks.

Sub-commands:

`webhooks list <streamId>`

List all webhooks for a stream.

postject webhooks list stream_xyz789

`webhooks create <streamId> <url>`

Create a new webhook.

Options:

-e, --events <events...> - Event types (default: all events)

# Listen to all events
postject webhooks create stream_xyz789 https://app.com/webhook

# Specific events
postject webhooks create stream_xyz789 https://app.com/webhook \
  --events delivered bounced complained

`webhooks test <webhookId>`

Test a webhook.

postject webhooks test wh_abc123

`webhooks logs <webhookId>`

View webhook delivery logs.

Options:

-l, --limit <number> - Number of logs (default: 20)

postject webhooks logs wh_abc123 --limit 50

`webhooks delete <streamId> <webhookId>`

Delete a webhook.

postject webhooks delete stream_xyz789 wh_abc123

`postject export`

Export configuration to YAML/JSON.

Options:

-f, --format <format> - Output format: yaml|json (default: yaml)
-o, --output <file> - Output file path

Examples:

# Export to YAML (stdout)
postject export

# Export to file
postject export --format json --output config.json

`postject import <file>`

Import configuration from YAML/JSON file.

postject import config.yaml

Environment Variables

You can use environment variables instead of the config file:

POSTJECT_API_KEY - Your API key
POSTJECT_BASE_URL - API base URL

Example:

export POSTJECT_API_KEY=pk_live_your_key_here
postject send --to [email protected] --subject "Test" --body "<p>Test</p>"

Configuration File

Config is stored at ~/.postject/config.json:

{
  "apiKey": "pk_live_your_key_here",
  "baseUrl": "https://api.postject.com",
  "defaultServer": "srv_abc123",
  "defaultStream": "stream_xyz789"
}

Examples

Send a Welcome Email

postject send \
  --to [email protected] \
  --subject "Welcome to Acme Inc!" \
  --body "<h1>Welcome!</h1><p>Thanks for signing up.</p>"

Send Using Template

postject send \
  --to [email protected] \
  --template tpl_order_confirmation \
  --vars '{"orderNumber":"12345","total":"$99.99"}'

Monitor Message Status

# Get message ID from send command
postject send --to [email protected] --subject "Test" --body "<p>Test</p>"
# Output: Message ID: msg_abc123

# View detailed status
postject logs --message msg_abc123

Batch Operations

# Create multiple servers
for name in "Production" "Staging" "Development"; do
  postject servers create "$name"
done

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

Webhook Testing

# Create webhook
postject webhooks create stream_xyz789 https://myapp.com/webhooks

# Test it
postject webhooks test wh_abc123

# Check delivery logs
postject webhooks logs wh_abc123

Shell Completions

Generate shell completions for auto-complete:

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

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

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

$ postject send --to [email protected]
✗ API key not configured. Run "postject init" first.

Exit codes:

0 - Success
1 - Error (API error, validation error, etc.)

Debugging

Enable verbose output:

DEBUG=postject:* postject send --to [email protected] ...

Support

Documentation: https://postject.com/docs/cli
Email: [email protected]

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Postject CLI

Installation

Quick Start

Commands

postject init

postject send

postject logs

postject analytics

postject servers

servers list

servers create <name>

servers delete <id>

postject streams

streams list <serverId>

streams create <serverId> <name>

streams delete <serverId> <streamId>

postject templates

templates list <serverId>

templates create <serverId> <name>

templates delete <serverId> <templateId>

postject webhooks

webhooks list <streamId>

webhooks create <streamId> <url>

webhooks test <webhookId>

webhooks logs <webhookId>

webhooks delete <streamId> <webhookId>

postject export

postject import <file>

Environment Variables

Configuration File

Examples

Send a Welcome Email

Send Using Template

Monitor Message Status

Batch Operations

Webhook Testing

Shell Completions

Error Handling

Debugging

Support

License

`postject init`

`postject send`

`postject logs`

`postject analytics`

`postject servers`

`servers list`

`servers create <name>`

`servers delete <id>`

`postject streams`

`streams list <serverId>`

`streams create <serverId> <name>`

`streams delete <serverId> <streamId>`

`postject templates`

`templates list <serverId>`

`templates create <serverId> <name>`

`templates delete <serverId> <templateId>`

`postject webhooks`

`webhooks list <streamId>`

`webhooks create <streamId> <url>`

`webhooks test <webhookId>`

`webhooks logs <webhookId>`

`webhooks delete <streamId> <webhookId>`

`postject export`

`postject import <file>`