Courier CLI recipes: send, debug, and script notifications

One block per task, checked against CLI v5.6.0. first, and export COURIER_API_KEY.

export COURIER_API_KEY=YOUR_COURIER_API_KEY

How flags build the request

Every command maps to one REST endpoint, and its flags become the request body. Three rules decide the shape, and the first two are behind most failed commands.

The first positional argument fills the command’s ID. courier profiles retrieve user_123 and --user-id user_123 send the same request. A second positional is rejected, so a command with two IDs takes named flags for both.
A repeated flag builds an array. --user, --list, --patch, and --status each take one item. Pass the flag once per item, not a JSON array, which the CLI rejects.
A dotted flag sets one nested field. --message.to writes message.to, so you can build a send one field at a time.

Add --help to any command for its flags, and --debug to print the request it sent.

Send

Send a template to a user

Only a published template sends. The response carries a requestId, which is also the message ID for a single-recipient send.

courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.data '{"orderId": "ORD-456"}'

Send to an email address without a template

content replaces template, so send one or the other. routing with method: single sends on the first channel in the list that can reach the recipient.

courier send message \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"title": "Your export is ready", "body": "Download it from your dashboard."}' \
  --message.routing '{"method": "single", "channels": ["email"]}'

Retry a send without sending twice

The CLI sets the Idempotency-Key header. Reuse the key when a call times out or the connection drops, and Courier replays the first response instead of sending again. The replay includes errors. For 24 hours a key that got a 400 keeps returning it, so use a new key once you fix the request.

courier send message \
  --idempotency-key "order-456-confirmation" \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40"

Tag a send so you can find it later

Set tags or a trace_id in the send’s metadata, then filter the message list by either. A trace_id from your own system, such as an order ID, finds every message one request produced without storing Courier’s IDs.

courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --message.metadata '{"tags": ["onboarding"], "trace_id": "order-456"}'

courier messages list --tag onboarding
courier messages list --trace-id order-456

Send a body from a file

The CLI reads a JSON request body from stdin. A flag doesn’t override a piped body. Where both set the same field, the file wins without a warning, so put everything in the file.

courier send message < message.json

Send to a list

Subscribe the user to the list, then send to the list ID. Every subscriber gets the message.

courier lists retrieve acme-corp.beta-testers
courier profiles:lists subscribe user_123 --list '{"listId": "acme-corp.beta-testers"}'
courier send message \
  --message.to '{"list_id": "acme-corp.beta-testers"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40"

Send in bulk

Four calls in order. The job holds the recipients, and nothing sends until you run it. message.event is required and takes a template ID. Put the email in profile.email, not to.email, because routing reads the profile. courier bulk list-users JOB_ID shows the per-recipient outcome once the job has run. See for the full walkthrough.

courier bulk create-job --message '{"event": "nt_01kx4h2jdafq8bk9aftxak4b40", "data": {"company_name": "Acme Corp"}}'
courier bulk add-users --job-id JOB_ID \
  --user '{"to": {"user_id": "user_123"}, "profile": {"email": "sarah@acme-corp.com"}}' \
  --user '{"to": {"user_id": "user_456"}, "profile": {"email": "kai@acme-corp.com"}}'
courier bulk run-job JOB_ID
courier bulk retrieve-job JOB_ID

Debug a delivery

Read what happened to one message

history is the one to reach for first. It returns each status change with its reason, which tells you whether a message was never routed, was rejected by the provider, or was delivered and never opened. content shows what actually rendered, which separates a template bug from a delivery one.

courier messages history <message_id>
courier messages content <message_id>

Find failed messages

Filter by status and time, then trim the output with --transform. It takes a GJSON path, so the output is one {id, status, reason} object per message. lists what each status and reason means.

courier messages list \
  --status UNDELIVERABLE --status UNROUTABLE \
  --enqueued-after 2026-09-22T00:00:00Z \
  --format json \
  --transform 'results.#.{id,status,reason}'

Resend or cancel a message

resend creates a new message with a new ID. cancel only stops a message that is still in the delivery pipeline.

courier messages resend <message_id>
courier messages cancel <message_id>

Check a template’s delivery rates

get-metrics returns sent, delivered, opened, and clicked counts over time. The counters are nested, so every delivered message is also counted in sent. Read them as rates, not as parts of a total. covers the window limits.

courier notifications get-metrics \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --lookback P7D \
  --granularity DAY

Manage recipients

Create, update, and delete a profile

create merges into an existing profile. replace overwrites it, so include every field you want to keep. update takes JSON Patch operations, one --patch flag per operation.

courier profiles create user_123 --profile '{"email": "sarah@acme-corp.com"}'
courier profiles retrieve user_123
courier profiles update user_123 --patch '{"op": "replace", "path": "/phone_number", "value": "+15555550123"}'
courier profiles delete user_123

Import profiles from a CSV

Loop over the rows and create one profile per line. End each call with < /dev/null. Without it the CLI reads the rest of the file as its request body, so the loop stops after the first row with a merge error. jq builds the JSON, which keeps a stray quote in the data from breaking the command.

tail -n +2 users.csv | while IFS=, read -r user_id email; do
  courier profiles create "$user_id" \
    --profile "$(jq -nc --arg email "$email" '{email: $email}')" < /dev/null
done

Register a push token

--provider-key is firebase-fcm, apn, expo, or onesignal. Use the key of the provider that issued the token.

courier users:tokens add-single \
  --user-id user_123 \
  --token YOUR_DEVICE_TOKEN \
  --provider-key firebase-fcm

Issue a JWT for Inbox

Issue the token a client SDK, such as Inbox, signs in with. The user_id scope decides whose messages it can read, so issue one per signed-in user and never share one across users.

courier auth issue-token \
  --scope "user_id:user_123 inbox:read:messages inbox:write:events" \
  --expires-in "7 days"

Manage preferences

Send has_custom_routing and the full custom_routing array together, because the write replaces the topic’s routing rather than merging into it.

courier users:preferences retrieve user_123
courier users:preferences update-or-create-topic \
  --user-id user_123 \
  --topic-id YOUR_TOPIC_ID \
  --topic '{"status": "OPTED_IN", "has_custom_routing": true, "custom_routing": ["email"]}'

Add a user to a tenant

tenants update creates the tenant or replaces it, so pass every field you want to keep, such as --brand-id.

courier tenants update acme-corp --name "Acme Corp"
courier users:tenants add-single --user-id user_123 --tenant-id acme-corp
courier tenants list-users acme-corp

Manage templates

A write leaves a draft. publish is what makes it live, and a send resolves the published version, so a content change nothing published reaches no recipient. Read the draft with --version draft before you publish it.

courier notifications list
courier notifications retrieve-content nt_01kx4h2jdafq8bk9aftxak4b40 --version draft
courier notifications put-content nt_01kx4h2jdafq8bk9aftxak4b40 \
  --content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Your order shipped."}]}'
courier notifications publish nt_01kx4h2jdafq8bk9aftxak4b40

Run journeys and broadcasts

Start a journey for a user

Only a published journey starts. data is available to every node for conditions and template variables.

courier journeys invoke \
  --template-id user-onboarding \
  --user-id user_123 \
  --data '{"first_name": "Sarah", "has_activated": false}'

Find journey runs that failed

list-steps shows each node the run reached and what happened there, including the message ID of every send. Runs are kept for 95 days.

courier journeys:runs list --template-id user-onboarding --status ERROR --format json --transform 'runs.#.run_id'
courier journeys:runs list-steps --run-id RUN_ID

Cancel journey runs

Cancel by token or by run ID, not both, or the call returns 400. A token cancels every run that shares it, and you set it in the journey’s settings. See .

courier journeys cancel --cancelation-token order-9042-flow
courier journeys cancel --run-id RUN_ID

Schedule a broadcast

--scheduled-to has no offset, because --timezone supplies it. Use broadcasts send with the same recipient flags to send now. A scheduled broadcast locks its content, so cancel with broadcasts cancel before editing it.

courier broadcasts create --name "March product update" --channel email
courier broadcasts put-content --broadcast-id BROADCAST_ID \
  --content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Here is what shipped in March."}]}'
courier broadcasts schedule --broadcast-id BROADCAST_ID \
  --recipient-type list --recipient-id acme-corp.beta-testers \
  --scheduled-to 2026-10-01T09:00:00 --timezone America/New_York

Release a digest early

release sends every recipient’s held digest for that schedule now, instead of at its next scheduled time.

courier digests:schedules release sch_01m26nhsf7fzxr5kngwf8p0b2c

Script the CLI

Page through every result

List commands return one page at a time. paging.more says whether another exists, and paging.cursor fetches it. The args array keeps the loop working in both bash and zsh.

cursor=""
while :; do
  args=()
  [ -n "$cursor" ] && args=(--cursor "$cursor")
  page=$(courier messages list --recipient user_123 --format json "${args[@]}")
  echo "$page" | jq -c '.results[]'
  [ "$(echo "$page" | jq -r '.paging.more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.paging.cursor')
done

Pull one field into a variable

Combine --transform with --raw-output to capture one value. --raw-output drops the JSON quotes from a string result, so the variable holds the bare ID.

request_id=$(courier send message \
  --message.to '{"user_id": "user_123"}' \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --format json --transform requestId --raw-output)

Use it in CI

Pass the key from your secret store and read json, because the default human format isn’t a stable contract. Double-quote any JSON that holds a shell variable. Inside single quotes $USER_ID is sent literally, and the send goes to a user named $USER_ID. The CLI exits non-zero on an API error, so a failed send fails the step without extra handling.

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to "{\"user_id\": \"$USER_ID\"}" \
  --message.template "nt_01kx4h2jdafq8bk9aftxak4b40" \
  --format json

Global flags

Every command takes these.

Flag	Use it to
`--api-key`	Override `COURIER_API_KEY` for one call.
`--format`	Set the output format: `auto`, `json`, `jsonl`, `pretty`, `raw`, `yaml`, or `explore`. Use `json` for anything a script reads.
`--transform`	Reshape the response with a GJSON path before it prints.
`--raw-output`, `-r`	Print a string result without JSON quotes.
`--format-error` / `--transform-error`	The same two, applied to an error response.
`--base-url`	Point at a different API host.
`--debug`	Print the request and response, for when a call fails and the error isn’t enough.

FAQ

What can the Courier CLI do?

The Courier CLI covers the full REST API from a terminal: sends, profiles, lists, templates, journeys, broadcasts, bulk jobs, tenants, preferences, and delivery logs. Each command maps to one endpoint, so anything in the has a CLI equivalent.

Why does a Courier CLI command reject a JSON array?

A Courier CLI flag that takes a list, such as --user, --list, --patch, or --status, takes one item per flag. Repeat the flag once per item and the CLI builds the array. Passing the whole array to one flag fails with a parse error.

How do I pass two IDs to a Courier CLI command?

The Courier CLI accepts one positional argument, which fills the command’s first ID. A command that needs two, such as a user and a topic, takes named flags like --user-id and --topic-id for both.

Should I use the Courier CLI or the MCP server?

Use the CLI for scripts, CI pipelines, and commands you run yourself, because its output is predictable and it exits non-zero on failure. Use the when an AI agent should decide which calls to make. Both call the same API with the same key.

Does the Courier CLI need Node.js?

The Courier CLI is a native binary. npm installs it and downloads the binary for your platform, and after that it runs without Node.js. You can also download the binary directly from GitHub Releases.

Get started

Tools

Courier CLI recipes: send, debug, and script notifications

How flags build the request

Send

Send a template to a user

Send to an email address without a template

Retry a send without sending twice

Tag a send so you can find it later

Send a body from a file

Send to a list

Send in bulk

Debug a delivery

Read what happened to one message

Find failed messages

Resend or cancel a message

Check a template’s delivery rates

Manage recipients

Create, update, and delete a profile

Import profiles from a CSV

Register a push token

Issue a JWT for Inbox

Manage preferences

Add a user to a tenant

Manage templates

Run journeys and broadcasts

Start a journey for a user

Find journey runs that failed

Cancel journey runs

Schedule a broadcast

Release a digest early

Script the CLI

Page through every result

Pull one field into a variable

Use it in CI

Global flags

FAQ

​How flags build the request

​Send

​Send a template to a user

​Send to an email address without a template

​Retry a send without sending twice

​Tag a send so you can find it later

​Send a body from a file

​Send to a list

​Send in bulk

​Debug a delivery

​Read what happened to one message

​Find failed messages

​Resend or cancel a message

​Check a template’s delivery rates

​Manage recipients

​Create, update, and delete a profile

​Import profiles from a CSV

​Register a push token

​Issue a JWT for Inbox

​Manage preferences

​Add a user to a tenant

​Manage templates

​Run journeys and broadcasts

​Start a journey for a user

​Find journey runs that failed

​Cancel journey runs

​Schedule a broadcast

​Release a digest early

​Script the CLI

​Page through every result

​Pull one field into a variable

​Use it in CI

​Global flags

​FAQ

How flags build the request

Send

Send a template to a user

Send to an email address without a template

Retry a send without sending twice

Tag a send so you can find it later

Send a body from a file

Send to a list

Send in bulk

Debug a delivery

Read what happened to one message

Find failed messages

Resend or cancel a message

Check a template’s delivery rates

Manage recipients

Create, update, and delete a profile

Import profiles from a CSV

Register a push token

Issue a JWT for Inbox

Manage preferences

Add a user to a tenant

Manage templates

Run journeys and broadcasts

Start a journey for a user

Find journey runs that failed

Cancel journey runs

Schedule a broadcast

Release a digest early

Script the CLI

Page through every result

Pull one field into a variable

Use it in CI

Global flags

FAQ