CLI Tool

The TrackPost CLI is a powerful command-line tool for managing emails, templates, and your account without writing code.

Table of Contents

Installation

Requirements

Node.js 18 or higher
npm or yarn

Install Globally

npm install -g @trackpost/cli

Verify Installation

trackpost --version

Expected output:

trackpost/1.0.0 darwin-arm64 node-v20.10.0

Tip

Pro Tip: Use npx to run without installing globally:

npx @trackpost/cli --version

Authentication

Authenticate the CLI with your TrackPost account:

trackpost auth login

You’ll be prompted to:

Enter your email address
Enter your password
Select a workspace

Using API Keys

For automation and CI/CD, use API keys directly:

# Set via environment variable
export TRACKPOST_API_KEY=tp_live_your_key

# Or pass with each command
trackpost send --to [email protected] --api-key tp_live_your_key

Logout

trackpost auth logout

Check Authentication Status

trackpost auth status

Sending Emails

Basic Email

trackpost send \
  --to [email protected] \
  --from [email protected] \
  --subject "Hello from TrackPost!" \
  --html "<h1>Welcome!</h1><p>Thanks for joining us.</p>"

With Text Version

trackpost send \
  --to [email protected] \
  --from [email protected] \
  --subject "Hello!" \
  --html "<h1>Welcome!</h1>" \
  --text "Welcome! Thanks for joining us."

Multiple Recipients

trackpost send \
  --to [email protected],[email protected] \
  --from [email protected] \
  --subject "Team Update" \
  --html "<h1>Weekly Update</h1>"

Using a Template

trackpost send \
  --to [email protected] \
  --from [email protected] \
  --template welcome_email \
  --variables '{"user_name":"John","company":"Acme Inc"}'

Send with Attachments

trackpost send \
  --to [email protected] \
  --from [email protected] \
  --subject "Your Invoice" \
  --html "<p>Please find your invoice attached.</p>" \
  --attachments ./invoice.pdf,./receipt.pdf

Using a JSON File

Create email.json:

{
  "to": "[email protected]",
  "from": "[email protected]",
  "subject": "Welcome!",
  "html": "<h1>Welcome!</h1>",
  "text": "Welcome!",
  "template_id": "welcome_email",
  "variables": {
    "user_name": "John"
  }
}

Send it:

trackpost send --file email.json

Managing Templates

List Templates

trackpost templates list

Output:

┌────────────────────┬──────────┬─────────────────┬──────────────┐
│ ID                 │ Name     │ Subject         │ Created      │
├────────────────────┼──────────┼─────────────────┼──────────────┤
│ tpl_abc123         │ Welcome  │ Welcome, {{name}}! │ 2025-01-10 │
│ tpl_def456         │ Reset    │ Reset your password │ 2025-01-12│
└────────────────────┴──────────┴─────────────────┴──────────────┘

Get Template Details

trackpost templates get tpl_abc123

Create Template from File

Create welcome.liquid:

<h1>Welcome, {{user_name}}!</h1>
<p>We're excited to have you at {{company}}.</p>
<a href="{{activation_link}}">Activate your account</a>

Create the template:

trackpost templates create \
  --name "welcome_email" \
  --subject "Welcome to {{company}}, {{user_name}}!" \
  --file welcome.liquid

Update Template

trackpost templates update tpl_abc123 \
  --file welcome-v2.liquid \
  --subject "Welcome to {{company}}!"

Delete Template

trackpost templates delete tpl_abc123

AWS Setup

Interactive Setup

The CLI includes an interactive wizard for AWS configuration:

trackpost aws setup

This will:

Ask for your AWS credentials
Select your preferred region
Configure SNS topics for webhooks
Test the connection

Validate Configuration

trackpost aws validate

Get AWS Status

trackpost aws status

Managing Emails

List Recent Emails

trackpost emails list

With options:

# Limit results
trackpost emails list --limit 10

# Filter by status
trackpost emails list --status delivered

# Filter by date range
trackpost emails list --from 2025-01-01 --to 2025-01-31

Get Email Details

trackpost emails get msg_abc123

Cancel Scheduled Email

trackpost emails cancel msg_abc123

API Keys

List API Keys

trackpost keys list

Create New Key

trackpost keys create \
  --name "Production API Key" \
  --environment live \
  --rate-limit 60

Revoke Key

trackpost keys revoke key_abc123

Webhooks

List Webhooks

trackpost webhooks list

Create Webhook

trackpost webhooks create \
  --url https://yourapp.com/webhooks/trackpost \
  --events email.delivered,email.bounced

Delete Webhook

trackpost webhooks delete wh_abc123

Domains

List Domains

trackpost domains list

Verify Domain DNS

trackpost domains verify yourdomain.com

Get Domain Details

trackpost domains get yourdomain.com

Account Management

Get Account Info

trackpost account info

Get Usage Statistics

trackpost account usage

Get Current Plan

trackpost account plan

Advanced Usage

Batch Operations

Send multiple emails from a CSV file:

Create recipients.csv:

email,name,company
[email protected],John,Acme Inc
[email protected],Jane,TechCorp

Send:

trackpost batch send \
  --file recipients.csv \
  --template welcome_email \
  --mapping email:to,name:user_name,company:company

JSON Output

For scripting, use JSON output:

trackpost emails list --json

Quiet Mode

Suppress all output except errors:

trackpost send --to [email protected] --quiet

Dry Run

Test without actually sending:

trackpost send --to [email protected] --dry-run

Configuration

Global Configuration

The CLI stores configuration in ~/.trackpost/config.json:

{
  "api_key": "tp_live_...",
  "workspace_id": "ws_abc123",
  "default_from": "[email protected]",
  "format": "table"
}

Set Configuration

trackpost config set default_from [email protected]
trackpost config set format json

View Configuration

trackpost config get

CI/CD Integration

GitHub Actions Example

name: Deploy and Notify
on: [push]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Send deployment notification
        env:
          TRACKPOST_API_KEY: ${{ secrets.TRACKPOST_API_KEY }}
        run: |
          npx @trackpost/cli send \
            --to [email protected] \
            --from [email protected] \
            --subject "Deployment: ${{ github.ref }}" \
            --text "New deployment to production"

Exit Codes

The CLI returns standard exit codes:

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Rate limit exceeded
4	Invalid arguments
5	API error

Environment Variables

Variable	Description
`TRACKPOST_API_KEY`	Your API key
`TRACKPOST_WORKSPACE_ID`	Default workspace
`TRACKPOST_API_URL`	Custom API endpoint
`TRACKPOST_DEBUG`	Enable debug logging

Next Steps

Node.js SDK - Integrate programmatically
Templates - Create email templates
API Reference - Full API documentation