Courier CLI recipes

One block per task. first, and export COURIER_API_KEY.

export COURIER_API_KEY=YOUR_COURIER_API_KEY

Send a notification

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

Only a published template sends. To send without one, pass --message.content with a JSON object holding title and body, instead of --message.template.

Manage profiles

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":"/email","value":"sarah@acme-corp.com"}]'
courier profiles delete user_123

create merges into an existing profile. replace overwrites it, so include every field you want to keep.

Check a message

courier messages retrieve <message_id>
courier messages list --recipient "user_123" --format json

Debug a delivery

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

history is the one to reach for first. It returns each event in the send with the status reason, which is what 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 resend <message_id>
courier messages cancel <message_id>

Send to a list

courier lists retrieve my-list
courier profiles:lists subscribe user_123 --lists '["my-list"]'
courier send message --message.to '{"list_id": "my-list"}' --message.template "weekly-digest"

Send in bulk

Four calls in order. The job holds the recipients, and nothing sends until you run it.

courier bulk create-job --message '{"template": "product-update"}'
courier bulk add-users <job_id> --users '[{"recipient":"user_123"},{"recipient":"user_456"}]'
courier bulk run-job <job_id>
courier bulk retrieve-job <job_id>

Add users in batches rather than one call per recipient. retrieve-job reports progress, and courier bulk list-users <job_id> shows the per-recipient outcome once it has run.

Manage templates

courier notifications list
courier notifications retrieve <template_id>
courier notifications put-content <template_id> --content '{"version":"2022-01-01","elements":[]}'
courier notifications publish <template_id>

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.

Manage tenants

courier tenants list
courier tenants update acme-corp --name "Acme Corp"
courier tenants list-users acme-corp

Manage preferences

courier users:preferences retrieve user_123
courier users:preferences update-or-create-topic user_123 <topic_id> \
  --status "OPTED_IN" --hasCustomRouting true --customRouting '["email"]'

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

Global flags

Every command takes these.

Flag	Use it to
`--api-key`	Override `COURIER_API_KEY` for one call.
`--format`	Set the output format, `json` for anything a script reads.
`--raw-output`	Print the response body with no wrapping.
`--transform`	Reshape the response before it prints.
`--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 is not enough.

Use it in CI

Pass the key from your secret store and read json rather than the human format, which is not a stable contract.

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

The CLI exits non-zero on an API error, so a failed send fails the step without extra handling. Use --transform to pull one field out for a later step rather than parsing the whole body.

Get started

Tools

Courier CLI recipes

Send a notification

Manage profiles

Check a message

Debug a delivery

Send to a list

Send in bulk

Manage templates

Manage tenants

Manage preferences

Global flags

Use it in CI

​Send a notification

​Manage profiles

​Check a message

​Debug a delivery

​Send to a list

​Send in bulk

​Manage templates

​Manage tenants

​Manage preferences

​Global flags

​Use it in CI

Send a notification

Manage profiles

Check a message

Debug a delivery

Send to a list

Send in bulk

Manage templates

Manage tenants

Manage preferences

Global flags

Use it in CI