How to Manage Templates from the CLI and MCP

The Courier CLI and MCP server both wrap the Notification Templates REST API. The CLI runs as a native binary in your terminal; MCP lets your IDE agent (Cursor, VS Code Copilot, Claude Code, etc.) call Courier tools on your behalf. Both the CLI and MCP server cover the full template lifecycle: create, inspect, update, publish, send, version history, and archive. Every step in this tutorial shows both approaches side by side so you can pick the one that fits your workflow. By the end you will have created a draft template with Elemental content, published it, verified the published body, sent a test message, checked version history, and archived the template when you’re done.

This tutorial covers workspace-level notification templates (/notifications). For tenant-scoped templates used with the embeddable Courier Create editor, see How to Use the Courier Create API.

Prerequisites

Courier API key
CLI path: Install the Courier CLI (npm i -g @trycourier/cli)
MCP path: Add the Courier MCP server to your IDE

Export your key (the CLI reads it automatically; MCP reads it from your server config):

export COURIER_API_KEY="your-api-key"

Step 1 - List existing templates

Start by seeing what is already on your workspace.

courier notifications list

List my notification templates.

curl -s "https://api.courier.com/notifications" \
  -H "Authorization: Bearer $COURIER_API_KEY" | jq .

The response includes a results array of templates and a paging object. Note the id of any template you want to inspect further. Courier template ids look like nt_....

Step 2 - Create a draft template

Create a new notification template with Elemental content. The example builds a shipping-update email with a subject line, a text block, and a call-to-action button.

courier notifications create \
  --state DRAFT \
  --notification '{
    "name": "Shipping Update",
    "tags": [],
    "brand": null,
    "subscription": null,
    "routing": { "strategy_id": "YOUR_STRATEGY_ID" },
    "content": {
      "version": "2022-01-01",
      "elements": [
        { "type": "meta", "title": "Your order {{order_id}} has shipped" },
        {
          "type": "text",
          "content": "Hi {{name}}, your package is on the way. Tracking number: {{tracking_url}}."
        },
        {
          "type": "action",
          "content": "Track shipment",
          "href": "{{tracking_url}}"
        }
      ]
    }
  }'

Create a draft notification template called "Shipping Update"
with routing strategy YOUR_STRATEGY_ID and Elemental content:
- meta: "Your order {{order_id}} has shipped"
- text: "Hi {{name}}, your package is on the way. Tracking number: {{tracking_url}}."
- action: "Track shipment" linking to {{tracking_url}}

curl -X POST "https://api.courier.com/notifications" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "published": false,
    "notification": {
      "name": "Shipping Update",
      "tags": [],
      "brand": null,
      "subscription": null,
      "routing": { "strategy_id": "YOUR_STRATEGY_ID" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          { "type": "meta", "title": "Your order {{order_id}} has shipped" },
          {
            "type": "text",
            "content": "Hi {{name}}, your package is on the way. Tracking number: {{tracking_url}}."
          },
          {
            "type": "action",
            "content": "Track shipment",
            "href": "{{tracking_url}}"
          }
        ]
      }
    }
  }'

The response contains an id field. Save this as your TEMPLATE_ID.

export TEMPLATE_ID="nt_..."

Where does strategy_id come from? Every template needs a routing strategy that defines which channels to use and in what order. You can list existing strategies with courier routing-strategies list or grab one from an existing template in Studio. See How to Use the Templates API for a full walkthrough.

Step 3 - Inspect the draft

Verify the draft content before publishing. Use retrieve-content --version draft on the CLI; the MCP server has a dedicated get_notification_draft_content tool.

courier notifications retrieve-content --id $TEMPLATE_ID --version draft

Get the draft content for notification template nt_...

curl -s "https://api.courier.com/notifications/$TEMPLATE_ID/draft/content" \
  -H "Authorization: Bearer $COURIER_API_KEY" | jq .

The response shows your Elemental blocks exactly as stored. If anything looks wrong, you can replace the content in Step 4 before publishing.

Step 4 - Update the content (optional)

Need to tweak the draft? Use put-content to replace just the Elemental content without touching the template’s name, routing, or other metadata.

courier notifications put-content --id $TEMPLATE_ID \
  --state DRAFT \
  --content '{
    "version": "2022-01-01",
    "elements": [
      { "type": "meta", "title": "Order {{order_id}} - Shipped!" },
      {
        "type": "text",
        "content": "Good news, {{name}}! Your package shipped today and should arrive by {{eta}}."
      },
      {
        "type": "action",
        "content": "Track your package",
        "href": "{{tracking_url}}"
      }
    ]
  }'

Update the content for notification template TEMPLATE_ID:
- meta: "Order {{order_id}} - Shipped!"
- text: "Good news, {{name}}! Your package shipped today and should arrive by {{eta}}."
- action: "Track your package" linking to {{tracking_url}}

curl -X PUT "https://api.courier.com/notifications/$TEMPLATE_ID/draft/content" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "version": "2022-01-01",
      "elements": [
        { "type": "meta", "title": "Order {{order_id}} - Shipped!" },
        {
          "type": "text",
          "content": "Good news, {{name}}! Your package shipped today and should arrive by {{eta}}."
        },
        {
          "type": "action",
          "content": "Track your package",
          "href": "{{tracking_url}}"
        }
      ]
    }
  }'

To replace the entire template (name, routing, content, and all), use courier notifications replace --id $TEMPLATE_ID --notification '{...}' instead. That’s a full overwrite; include every field you want to keep.

Step 5 - Publish

Make the current draft live. Recipients will see this version the next time you send.

courier notifications publish --id $TEMPLATE_ID

Publish notification template TEMPLATE_ID.

curl -X POST "https://api.courier.com/notifications/$TEMPLATE_ID/publish" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Step 6 - Verify the published content

Read back the live version to confirm what recipients will see.

courier notifications retrieve-content --id $TEMPLATE_ID

Get the published content for notification template nt_...

curl -s "https://api.courier.com/notifications/$TEMPLATE_ID/content" \
  -H "Authorization: Bearer $COURIER_API_KEY" | jq .

retrieve-content defaults to the published version. Add --version draft to see the draft. After a publish they will match, but they can differ if you edit the draft without publishing again.

Step 7 - Send a test message

Fire a notification using your template. The data fields must match the {{variables}} in your Elemental content.

courier send message --message '{
  "template": "'"$TEMPLATE_ID"'",
  "to": { "email": "you@example.com" },
  "data": {
    "order_id": "ORD-42",
    "name": "Alex",
    "eta": "May 15",
    "tracking_url": "https://example.com/track/ORD-42"
  }
}'

Send a message using template nt_... to user user_123
with data: order_id "ORD-42", name "Alex", eta "May 15",
tracking_url "https://example.com/track/ORD-42".

curl -X POST "https://api.courier.com/send" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "'"$TEMPLATE_ID"'",
      "to": { "email": "you@example.com" },
      "data": {
        "order_id": "ORD-42",
        "name": "Alex",
        "eta": "May 15",
        "tracking_url": "https://example.com/track/ORD-42"
      }
    }
  }'

The response returns a requestId. Check delivery status in Message Logs or by calling courier messages list.

Step 8 - Check version history

See every published version of the template.

courier notifications list-versions --id $TEMPLATE_ID

List the version history for notification template TEMPLATE_ID.

curl -s "https://api.courier.com/notifications/$TEMPLATE_ID/versions" \
  -H "Authorization: Bearer $COURIER_API_KEY" | jq .

Each version has a created_at timestamp and a version string you can use to inspect or publish a specific historical snapshot.

Step 9 - Archive the template

When a template is no longer needed, archive it. Archived templates stop delivering but are not permanently deleted.

courier notifications archive --id $TEMPLATE_ID

Archive notification template TEMPLATE_ID.

curl -X DELETE "https://api.courier.com/notifications/$TEMPLATE_ID" \
  -H "Authorization: Bearer $COURIER_API_KEY"

CLI and MCP coverage

Step	CLI	MCP	cURL
List templates	`notifications list`	`list_notifications`	`GET /notifications`
Create	`notifications create`	`create_notification`	`POST /notifications`
Read draft	`notifications retrieve-content --version draft`	`get_notification_draft_content`	`GET /notifications/{id}/draft/content`
Update content	`notifications put-content`	`put_notification_content`	`PUT /notifications/{id}/draft/content`
Publish	`notifications publish`	`publish_notification`	`POST /notifications/{id}/publish`
Read published	`notifications retrieve-content`	`get_notification_content`	`GET /notifications/{id}/content`
Send	`send message`	`send_message_template`	`POST /send`
Versions	`notifications list-versions`	`list_notification_versions`	`GET /notifications/{id}/versions`
Archive	`notifications archive`	`archive_notification`	`DELETE /notifications/{id}`

Tips for CI / automation

Idempotent updates: Use courier notifications replace --id nt_... (or PUT /notifications/{id}) to overwrite a template by id, making deploys repeatable.
JSON output: Add --format json to any CLI command for machine-parseable output; pipe through jq for filtering.
Dry runs with test keys: Use a Test environment API key to iterate without sending real notifications.
MCP in CI: The MCP server can be called from any MCP-compatible runtime, not just IDEs. Use it in custom automation scripts that support the Model Context Protocol.

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

How to Manage Templates from the CLI and MCP

Prerequisites

Step 1 - List existing templates

Step 2 - Create a draft template

Step 3 - Inspect the draft

Step 4 - Update the content (optional)

Step 5 - Publish

Step 6 - Verify the published content

Step 7 - Send a test message

Step 8 - Check version history

Step 9 - Archive the template

CLI and MCP coverage

Tips for CI / automation

​Prerequisites

​Step 1 - List existing templates

​Step 2 - Create a draft template

​Step 3 - Inspect the draft

​Step 4 - Update the content (optional)

​Step 5 - Publish

​Step 6 - Verify the published content

​Step 7 - Send a test message

​Step 8 - Check version history

​Step 9 - Archive the template

​CLI and MCP coverage

​Tips for CI / automation

Prerequisites

Step 1 - List existing templates

Step 2 - Create a draft template

Step 3 - Inspect the draft

Step 4 - Update the content (optional)

Step 5 - Publish

Step 6 - Verify the published content

Step 7 - Send a test message

Step 8 - Check version history

Step 9 - Archive the template

CLI and MCP coverage

Tips for CI / automation