CLI

The helo CLI covers the whole Helo API from your terminal: send email, manage domains, channels and webhooks, and look up activity and statistics. Its output is JSON, so it works well in scripts and with AI agents too.

Install

Homebrew
Install script
Go
Windows

On macOS or Linux:

brew install helo-email/tap/helo

Use the full name helo-email/tap/helo. Plain helo installs an unrelated app.

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/helo-email/helo-cli/main/install.sh | sh

The script downloads the latest release for your platform, verifies its checksum and installs helo to ~/.local/bin. Set HELO_INSTALL_DIR to install it somewhere else.

With Go installed:

go install github.com/helo-email/helo-cli/cmd/helo@latest

Download the .zip for your architecture from the latest release, extract helo.exe, and put it in a folder on your PATH.

On macOS, install with Homebrew or the install script rather than downloading the archive in your browser. macOS blocks browser-downloaded binaries that aren’t notarized by Apple.

Check that it works:

helo --version

Authenticate

The CLI authenticates with an API credential. Set it as an environment variable:

export HELO_API_KEY="your-api-key"

You can also pass it on each command with --token. If your credential can send through more than one Channel, also set the Channel to send through:

export HELO_CHANNEL_ID="your-channel-id"

Commands that send take --channel-id to override it.

Send an email

helo sending send-transactional \
  --from '{"email": "you@yourdomain.com", "name": "Your Name"}' \
  --to '[{"email": "recipient@example.com"}]' \
  --subject "Hello from Helo" \
  --text "This is a test message, delivered with <3 by Helo."

While your account is in test mode, you can only send to email addresses on domains you have verified.

Add --dry-run to any command to print the request it would send, without sending it.

Common commands

helo domains list                                                # list your domains
helo channels list                                               # list your Channels
helo activity list-messages --start-date 24h                     # messages from the last 24 hours
helo statistics retrieve-daily --from 7d --to 0d --timezone UTC  # daily statistics for the last week

Run helo --help to list every command, and helo <command> --help for a command’s flags.

Input and output

Each field of a request body has its own flag. You can also pass the whole body as JSON with --data, inline or from a file:

helo sending send-transactional --data @message.json

Results print to stdout as JSON:

{
  "ok": true,
  "data": { ... }
}

Add --quiet to print only data, which is handy for piping into jq:

helo domains list --quiet | jq '.results[].name'

Errors go to stderr. Each kind of error has its own exit code, so scripts can tell them apart: 3 means a credential problem, 5 means the API rejected the request, and 6 means a retry may help. Run helo --help for the full list.

Getting started

Core concepts

Platforms

Account management

Install

Authenticate

Send an email

Common commands

Input and output

​Install

​Authenticate

​Send an email

​Common commands

​Input and output

Install

Authenticate

Send an email

Common commands

Input and output