Postscale CLI Quickstart

The Postscale CLI is a command-line tool for configuring domains, sending email, and inspecting outbound messages, inbound email, and webhook deliveries. This guide walks through your first simulated send with version 1.0.0.

Install the CLI

On macOS or Linux with Homebrew:

brew install postscale/tap/postscale
postscale --version

For Windows or installation without Homebrew, download a prebuilt binary from the GitHub release. Follow the installation instructions to verify its checksum and add the binary to your PATH. Prebuilt binaries do not require Go.

Authenticate with a test API key

Create a test API key in the Postscale dashboard, then set POSTSCALE_API_KEY through your shell or secret manager. Test keys start with ps_test_.

Save the key as a named profile in your operating system's keychain:

postscale auth login --profile test
postscale auth status --profile test

The profile name is only a label. A ps_test_ key enables simulated sending; a ps_live_ key submits real email. auth status reports local configuration without making a request to validate the key.

On a headless machine without a supported keychain, keep using POSTSCALE_API_KEY and omit --profile test from the commands below.

Set up your sending domain

Test sends still require a verified sending domain in your account. Add a domain you control and retrieve its DNS records, replacing example.com below:

postscale domains create example.com --profile test
postscale domains dns example.com --profile test

If the domain already exists, skip creation. Add the returned records with your DNS provider, then verify them:

postscale domains verify example.com --profile test

Follow the domain setup guide for the DNS requirements. Test keys simulate email sending; domain commands still change your account's configuration.

Validate and send a message

Create a file named message.json, replacing the sender with an address on your verified domain:

{
  "from": "sender@example.com",
  "to": ["recipient@example.net"],
  "subject": "Hello from the Postscale CLI",
  "text_body": "My first command-line email."
}

Validate it locally, then submit it with your test profile:

postscale emails send --file message.json --dry-run
postscale emails send --file message.json --profile test --json

The dry-run checks input without credentials or network requests. Sending with a test key records a simulated message without delivery, quota usage, or delivery webhooks. A successful simulation confirms API validation, not inbox delivery.

Inspect the result

postscale emails list --subject "Hello from the Postscale CLI" --profile test
postscale emails get EMAIL_RESOURCE_UUID --profile test

Replace EMAIL_RESOURCE_UUID with the id returned by the list command. The send response's message_id is an SMTP identifier and cannot be used here.

For live messages, postscale emails events EMAIL_RESOURCE_UUID --profile live shows delivery events once you have configured a live profile.

Prepare for live sending

Once your account is approved for live sending, configure a separate live profile with a ps_live_ key. Update the message with your intended recipient before sending with --profile live.

The CLI reference covers all installation options, profile selection, inbound email, webhook diagnostics, pagination, and shell completion. Run postscale --help or postscale COMMAND --help for command-specific options.