Courier CLI

The Courier CLI is a native binary that covers the full Courier REST API. It works on macOS, Linux, and Windows with no runtime dependencies.

Prerequisite: Create an API Key

You need a Courier API key to authenticate CLI commands. Create one in your Courier Settings, then set it in your shell:

export COURIER_API_KEY="your-api-key"

If you pass --api-key on a command, it takes priority over the environment variable. This is useful for testing against a different workspace without changing your shell config. See Global Flags for all available flags.

Installation

npm
Direct download

npm install -g @trycourier/cli

This downloads a platform-specific binary via a postinstall step. No Node.js runtime is needed after installation.

Download the latest binary for your platform from GitHub Releases. Extract it and add it to your PATH.

Verify the installation:

courier --version

Command Structure

The CLI uses a resource-based pattern:

courier [resource] <command> [flags...]

Use --help on any command to see available flags:

courier send --help
courier messages list --help

Send Your First Notification

You don’t need a template to send your first notification. Pass the content inline and Courier handles the rest. Send an email directly

courier send message \
  --message.to.email "alex@example.com" \
  --message.content.title "New comment on your design file" \
  --message.content.body "Sara left a comment on Homepage Redesign: 'Love the new hero section — can we try a darker background?'"

Send across multiple channels Route a notification to email first, then fall back to SMS if email can’t be delivered. See channel priority for how Courier evaluates routing order.

courier send message \
  --message.to.email "alex@example.com" \
  --message.to.phone_number "+15551234567" \
  --message.content.title "New login detected" \
  --message.content.body "We noticed a new login to your account from {{city}}, {{country}}. If this wasn't you, reset your password immediately." \
  --message.data '{"city": "San Francisco", "country": "US"}' \
  --message.routing.method "single" \
  --message.routing.channels '["email", "sms"]'

Send using a template Once you’ve built a template in the Courier dashboard, reference it by ID or alias.

courier send message \
  --message.to.user_id "user-123" \
  --message.template "usage-alert" \
  --message.data '{"resource": "API calls", "used": 8000, "limit": 10000, "percentage": 80, "upgradeUrl": "https://app.example.com/billing"}'

Manage User Profiles

Courier needs to know where to reach your users. Create profiles with their contact info so you can send by user_id instead of passing email and phone every time. Create a user profile

courier profiles create \
  --user-id "user-123" \
  --profile '{"email": "alex@example.com", "phone_number": "+15551234567", "name": "Alex Chen"}'

Add custom attributes Custom data on the profile is available in all templates for that user.

courier profiles create \
  --user-id "user-123" \
  --profile '{"custom": {"plan": "pro", "company": "Acme Corp", "locale": "en-US"}}'

This merges with the existing profile, so you won’t overwrite the email or phone number you set earlier. Look up a user’s profile

courier profiles retrieve --user-id "user-123"

Check on a Notification

Every notification gets a message ID. Use it to check delivery status, inspect rendered content, or trace the full delivery timeline. Get the status of a sent notification

courier messages retrieve --message-id "1-abc123"

View the full delivery timeline See every step a notification went through (queued, sent, delivered, opened, clicked) with timestamps.

courier messages history --message-id "1-abc123"

See what was actually rendered Check the final content Courier sent to the provider, after all template variables and routing logic were applied.

courier messages output --message-id "1-abc123"

Debug a Delivery Issue

When a user reports they didn’t get a notification, run these in sequence to narrow it down. Find the notification Pull recent notifications for a specific user.

courier messages list --format json \
  --transform "results.#(recipient==user-123)"

Inspect the notification Check the status. Look for DELIVERED, SENT, UNDELIVERABLE, or UNROUTABLE.

courier messages retrieve --message-id "1-abc123" --format pretty

Trace the delivery steps The history shows exactly where things went wrong: did the provider reject it? Did routing skip a channel? Did a preference rule block it?

courier messages history --message-id "1-abc123" --format pretty

Verify the user’s profile If the notification is UNROUTABLE, the user’s profile is probably missing channel data.

courier profiles retrieve --user-id "user-123" --format pretty

Send to Groups

Create a list and add subscribers

courier lists update --list-id "beta-testers" --name "Beta Testers"

courier lists subscribe --list-id "beta-testers" --user-id "user-123"
courier lists subscribe --list-id "beta-testers" --user-id "user-456"
courier lists subscribe --list-id "beta-testers" --user-id "user-789"

Send to the whole list

courier send message \
  --message.to.list_id "beta-testers" \
  --message.template "feature-announcement" \
  --message.data '{"feature": "Design Studio", "releaseDate": "2026-03-15"}'

Send to multiple lists with a pattern If your list IDs follow a hierarchy (like eng.frontend, eng.backend), target all of them at once.

courier send message \
  --message.to.list_pattern "eng.*" \
  --message.template "engineering-update"

Send in Bulk

For large sends (product launches, monthly digests, migration emails), use the bulk API to send to thousands of users in a single job.

# Create the job
courier bulk create --message.template "monthly-digest"

# Add recipients (up to 1,000 per call)
courier bulk add-users --job-id "job-abc" \
  --users '[{"user_id": "user-1", "data": {"highlights": 12}}, {"user_id": "user-2", "data": {"highlights": 7}}]'

# Start sending
courier bulk run --job-id "job-abc"

# Check progress
courier bulk retrieve --job-id "job-abc"

Manage Templates

Notification templates let you define reusable content and routing in Courier’s designer, then send by template ID. The V2 workflow is: create → add content → create a routing strategy → publish → send. Create a draft template

courier notifications create \
  --notification '{"name": "password-reset", "tags": ["transactional"], "content": {"version": "2022-01-01", "elements": []}}' \
  --state "DRAFT"

The response includes the template ID (nt_...). Use that ID in all subsequent commands. Add content to the template

courier notifications put-content \
  --id "nt_01abc123" \
  --content '{"version": "2022-01-01", "elements": [{"type": "channel", "channel": "email", "elements": [{"type": "meta", "title": "Reset your password"}, {"type": "text", "content": "Click the link below to reset your password. This link expires in 15 minutes."}]}]}' \
  --state "DRAFT"

Create a routing strategy A routing strategy controls which channels to use and in what order. You can reuse one strategy across multiple templates.

courier routing-strategies create \
  --name "transactional-email" \
  --routing '{"method": "single", "channels": ["email"]}'

Copy the strategy ID (rs_...) from the response, then link it to your template:

courier notifications replace \
  --id "nt_01abc123" \
  --notification '{"name": "password-reset", "tags": ["transactional"], "routing": {"strategy_id": "rs_01xyz"}, "content": {"version": "2022-01-01", "elements": []}}'

Publish the template

courier notifications publish --id "nt_01abc123"

This returns 204 when successful. The template is now live and referenceable by alias (password-reset) or ID. Send using the template

courier send message \
  --message.to.user_id "user-123" \
  --message.template "password-reset" \
  --message.data '{"resetUrl": "https://app.example.com/reset?token=abc"}'

List and inspect templates

# List all templates in your workspace
courier notifications list

# Check current published or draft content
courier notifications retrieve-content --id "nt_01abc123" --version draft

Work with Tenants

If you’re building a B2B product, tenants let you scope branding, preferences, and notification behavior per customer organization. Create a tenant

courier tenants create \
  --tenant-id "acme-corp" \
  --name "Acme Corp" \
  --properties '{"brandId": "brand-acme", "domain": "acme.com"}'

Add a user to a tenant

courier user-tenants add \
  --user-id "user-123" \
  --tenant-id "acme-corp"

Send with tenant context This applies the tenant’s brand and preferences automatically.

courier send message \
  --message.to.user_id "user-123" \
  --message.to.tenant_id "acme-corp" \
  --message.template "welcome-email"

Trigger Automations

Automations let you orchestrate multi-step notification sequences (delays, conditions, batching) without writing that logic in your app. Invoke a saved automation

courier automations invoke \
  --template-id "onboarding-sequence" \
  --data '{"userId": "user-123", "plan": "pro"}'

List available automations

courier automations list

Manage Preferences

Let users control what they receive. Preferences are enforced at send time; Courier won’t deliver a notification if the user has opted out of that topic. Check a user’s current preferences

courier preferences retrieve --user-id "user-123" --format pretty

View preferences for a specific topic

courier preferences retrieve-topic \
  --user-id "user-123" \
  --topic-id "marketing-updates"

Output Formats

Every command supports structured output via the --format flag:

Format	Description
`auto`	Default; human-readable for terminals, JSON for pipes
`json`	JSON output
`yaml`	YAML output
`pretty`	Colorized, indented JSON
`raw`	Raw response body
`jsonl`	Newline-delimited JSON (for streaming)

Filter output with GJSON syntax using --transform:

courier messages list --format json --transform "results.#.id"

Global Flags

Flag	Description
`--api-key`	Override `COURIER_API_KEY` for this command
`--base-url`	Use a custom API URL
`--format`	Output format (`auto`, `json`, `yaml`, `pretty`, `raw`, `jsonl`)
`--transform`	Filter output with GJSON syntax
`--debug`	Show HTTP request/response details
`--version`, `-v`	Print CLI version
`--help`	Show command usage

Scripting and CI/CD

Smoke-test a notification after deploy Run this in your CI pipeline to verify notifications still work after a deploy.

export COURIER_API_KEY="$COURIER_TEST_KEY"

courier send message \
  --message.to.user_id "smoke-test-user" \
  --message.template "welcome" \
  --format json

Store API keys as secrets in your CI provider (GitHub Actions secrets, GitLab CI variables, etc.) rather than hardcoding them.

Export recent notifications as JSON Useful for auditing or syncing with external systems.

courier messages list --format jsonl > messages-export.jsonl

Count notifications by status

courier messages list --format json \
  --transform "results.#.status" | sort | uniq -c

AI Agent Usage

The CLI works as a zero-config tool for AI agents in Cursor, Claude Code, Codex, and similar environments. Install once, set COURIER_API_KEY, and agents can run Courier operations directly via shell commands. Every command supports --format json for machine-readable output.

What’s Next

Manage Templates (CLI & MCP)

Step-by-step tutorial: create, publish, send, and archive templates from the CLI

MCP Server

Structured AI tool access for sending messages, managing users, and more

API Reference

Full REST API documentation

Source code: trycourier/courier-cli

Platform

Developer Tools

Help

Prerequisite: Create an API Key

Installation

Command Structure

Send Your First Notification

Manage User Profiles

Check on a Notification

Debug a Delivery Issue

Send to Groups

Send in Bulk

Manage Templates

Work with Tenants

Trigger Automations

Manage Preferences

Output Formats

Global Flags

Scripting and CI/CD

AI Agent Usage

What’s Next

Manage Templates (CLI & MCP)

MCP Server

API Reference

​Prerequisite: Create an API Key

​Installation

​Command Structure

​Send Your First Notification

​Manage User Profiles

​Check on a Notification

​Debug a Delivery Issue

​Send to Groups

​Send in Bulk

​Manage Templates

​Work with Tenants

​Trigger Automations

​Manage Preferences

​Output Formats

​Global Flags

​Scripting and CI/CD

​AI Agent Usage

​What’s Next

Manage Templates (CLI & MCP)

MCP Server

API Reference

Prerequisite: Create an API Key

Installation

Command Structure

Send Your First Notification

Manage User Profiles

Check on a Notification

Debug a Delivery Issue

Send to Groups

Send in Bulk

Manage Templates

Work with Tenants

Trigger Automations

Manage Preferences

Output Formats

Global Flags

Scripting and CI/CD

AI Agent Usage

What’s Next