Courier Notification Skills

Courier Notification Skills

Guidance for building deliverable and engaging notifications across all channels.

How to Use This Skill

1. Identify the task — What channel, notification type, or cross-cutting concern is the user working on?
2. Read only what's needed — Use the routing tables below to find the 1-2 files relevant to the task. Do NOT read all files.
3. Check for live docs — For current API signatures and SDK methods, fetch https://www.courier.com/docs/llms.txt
4. Synthesize before coding — Plan the complete implementation (channels, routing, error handling) before writing code.
5. Apply the rules — Each resource file starts with a "Quick Reference" section containing hard rules. Treat these as constraints, not suggestions.
6. Check universal rules — Before generating any notification code, verify it doesn't violate the Universal Rules below.

Handling Vague Requests

If the user's request doesn't clearly map to a specific channel, notification type, or guide, ask clarifying questions before reading any resource files. Don't guess — a wrong routing wastes time and produces irrelevant code.

Ask these questions as needed:

1. What channel? — "Which channel are you sending through: email, SMS, push, in-app, Slack, Teams, or WhatsApp?"
2. What type? — "Is this a transactional notification (triggered by a user action, like a password reset or order confirmation) or a marketing/growth notification (sent proactively, like a feature announcement)?"
3. New or existing? — "Are you starting from scratch, or do you have existing Courier code? If existing, what SDK packages do you have installed?"
4. What language? — "Are you using TypeScript/Node.js, Python, or another language?"

You don't need to ask all four — just the ones needed to route to the right 1-2 files. If the request is clearly about a specific topic (e.g., "help me with SMS"), skip the questions and go directly to the relevant resource.

Routing consequences of question 3 ("new or existing"):

| Answer | Skip | Load | |--------|------|------| | New to Courier / no existing code | (nothing) | [quickstart.md](./resources/guides/quickstart.md) + the relevant channel or type file | | Existing — has @trycourier/courier or trycourier installed | quickstart.md install + env-setup sections | Jump directly to channel or type file; assume client is constructed. Offer courier messages list as a one-line health check if useful. | | Existing — Inbox v7 (@trycourier/react-*) | v8 guidance | See "Courier Inbox Version Detection" block below, then [inbox-v7-legacy.md](./resources/channels/inbox-v7-legacy.md) |

Canonical SDK Shape

Before you write or evaluate any Courier code, ground it in this shape. If anything in a file below appears to contradict it, trust this block and fetch live docs to resolve — do not paste the contradicting snippet.

Node.js (@trycourier/courier):

import Courier from "@trycourier/courier";

// Reads process.env.COURIER_API_KEY by default
const client = new Courier();

await client.send.message({
  message: {
    to: { user_id: "user-123" },           // or { email }, { phone_number }, { list_id }, { tenant_id }, etc.
    template: "nt_01kmrbq6ypf25tsge12qek41r0", // OR content: { title, body } / { version, elements }
    data: { /* merge variables */ },
  },
}, {
  // Pass the Idempotency-Key via headers. Always set it explicitly here —
  // that is the one path guaranteed to be sent to the API across SDK
  // versions. Verify against your installed SDK version before relying on
  // any other `idempotencyKey` request option.
  headers: { "Idempotency-Key": "order-confirmation-12345" },
});

Python (trycourier):

from courier import Courier

# Reads COURIER_API_KEY from env by default
client = Courier()

client.send.message(
    message={
        "to": {"user_id": "user-123"},
        "template": "nt_01kmrbq6ypf25tsge12qek41r0",
        "data": {},
    },
    # Pass the Idempotency-Key via extra_headers. Python does not accept
    # idempotency_key= as a keyword argument — the header is the only way.
    extra_headers={"Idempotency-Key": "order-confirmation-12345"},
)

Method naming quick lookup (both SDKs follow the same structure, Node = camelCase, Python = snake_case):

| Operation | Node | Python | |-----------|------|--------| | Send a message | client.send.message({ message }) | client.send.message(message=...) | | Create a template | client.notifications.create({ notification, state }) → returns { id, name, content, … } at top level | client.notifications.create(notification=..., state=...) → response.id | | Publish a template | client.notifications.publish(templateId) | client.notifications.publish(template_id) | | Retrieve a message | client.messages.retrieve(id) | client.messages.retrieve(id) | | List messages | client.messages.list({ ... }) | client.messages.list(...) | | Subscribe a user to a list (additive) | client.lists.subscriptions.subscribeUser(userId, { list_id }) | client.lists.subscriptions.subscribe_user(user_id, list_id=...) | | Replace a list's subscribers | client.lists.subscriptions.subscribe(listId, { recipients }) | client.lists.subscriptions.subscribe(list_id, recipients=...) | | Create/replace a tenant | client.tenants.update(tenantId, body) | client.tenants.update(tenant_id, ...) | | Add a user to a tenant | client.users.tenants.addSingle(tenantId, { user_id }) | client.users.tenants.add_single(tenant_id, user_id=...) | | Create a bulk job | client.bulk.createJob({ message: { event } }) (event required) | client.bulk.create_job(message={"event": ...}) | | Create/update a profile (merge) | client.profiles.create(userId, { profile }) | client.profiles.create(user_id, profile=...) | | Get a user's preferences | client.users.preferences.retrieve(userId) | client.users.preferences.retrieve(user_id) | | Update a user's preference for a topic | client.users.preferences.updateOrCreateTopic(topicId, { user_id, topic: { status, ... } }) | client.users.preferences.update_or_create_topic(topic_id, user_id=..., topic=...) | | Register a user's device token | client.users.tokens.addSingle(token, { user_id, provider_key, device }) | client.users.tokens.add_single(token, user_id=..., provider_key=..., device=...) | | Create a journey | client.journeys.create({ name, nodes, enabled }) | client.journeys.create(name=..., nodes=..., enabled=...) | | Replace a journey (draft) | client.journeys.replace(id, { name, nodes, enabled }) | client.journeys.replace(id, name=..., nodes=..., enabled=...) | | Publish a journey | client.journeys.publish(id) | client.journeys.publish(id) | | Invoke a journey (start a run) | client.journeys.invoke(id, { user_id, data, profile }) → { runId } | client.journeys.invoke(template_id=id, user_id=..., data=..., profile=...) → .run_id | | Create a journey-scoped template | POST /journeys/{id}/templates (no SDK helper) | POST /journeys/{id}/templates (no SDK helper) | | Publish a journey-scoped template | POST /journeys/{id}/templates/{templateId}/publish (no SDK helper) | POST /journeys/{id}/templates/{templateId}/publish (no SDK helper) | | Trigger an automation (legacy) | client.automations.invoke.invokeByTemplate(templateId, { recipient, data }) | client.automations.invoke.invoke_by_template(template_id, recipient=..., data=...) | | Trigger an ad-hoc automation (legacy) | client.automations.invoke.invokeAdHoc({ recipient, automation }) | client.automations.invoke.invoke_ad_hoc(recipient=..., automation=...) | | Create a routing strategy | client.routingStrategies.create({ name, routing, channels?, providers? }) → returns { id: "rs_...", ... } | client.routing_strategies.create(name=..., routing=..., ...) | | Replace a routing strategy (full PUT) | client.routingStrategies.replace(id, { name, routing, ... }) | client.routing_strategies.replace(id, name=..., routing=..., ...) | | Configure a provider | client.providers.create({ provider, settings, title?, alias? }) | client.providers.create(provider=..., settings=..., ...) | | List provider catalog (required settings schema) | client.providers.catalog.list({ keys?, name?, channel? }) | client.providers.catalog.list(keys=..., channel=...) | | Cancel a message | client.messages.cancel(messageId) | client.messages.cancel(message_id) | | Retrieve a template | client.notifications.retrieve(templateId) | client.notifications.retrieve(template_id) | | List templates | client.notifications.list() | client.notifications.list() | | Replace a template (full PUT) | client.notifications.replace(templateId, { notification, state }) | client.notifications.replace(template_id, notification=..., state=...) | | Archive a template | client.notifications.archive(templateId) | client.notifications.archive(template_id) | | Get published template content | client.notifications.retrieveContent(templateId) | client.notifications.retrieve_content(template_id) |

> The table above covers the most common operations. [journeys.md](./resources/guides/journeys.md), [templates.md](./resources/guides/templates.md), [routing-strategies.md](./resources/guides/routing-strategies.md), and [providers.md](./resources/guides/providers.md) each contain their own complete SDK shape tables for CRUD on their respective resources (including list, retrieve, replace, archive). For new multi-step flows, use Journeys instead of Automations — see [Journeys](./resources/guides/journeys.md).

Shapes that do NOT exist (do not invent them):

• client.messages.archive(...) — archive is REST-only: POST /messages/{id}/archive. Note: client.notifications.archive(id) and client.routingStrategies.archive(id) / client.providers.archive(id) DO exist — this restriction is specific to the messages namespace.
• client.tenants.createOrReplace(...) — use client.tenants.update
• client.lists.subscribe(listId, userId) — use subscriptions.subscribeUser or subscriptions.subscribe
• Bulk createJob({ message: { template } }) without event — event is required
• client.users.preferences.update(...) — use client.users.preferences.updateOrCreateTopic(topicId, { user_id, topic }).
• client.automations.invoke(templateId, ...) — the real shape is client.automations.invoke.invokeByTemplate(...) or client.automations.invoke.invokeAdHoc(...). Note: for new multi-step flows, prefer Journeys (POST /journeys) over Automations.
• Journey management SDK methods (client.journeys.create/replace/publish/invoke) DO exist and should be preferred over raw REST. Journey-scoped template operations (POST /journeys/{id}/templates, .../publish) currently have no SDK helper — use REST/curl for those. Journeys are not in MCP yet.
• client.routing.create(...) / client.strategies.* — the real namespace is client.routingStrategies.* (Node) / client.routing_strategies.* (Python).
• client.integrations.* — there is no integrations namespace; provider configurations live under client.providers.* and the provider type catalog under client.providers.catalog.*.

Shapes that exist but should not be the default:

• client.profiles.update(userId, { patch: [...] }) — this DOES exist and applies a JSON Patch (RFC 6902). Use it only when the user specifically needs atomic field-level ops (add/remove/replace/test on specific paths). For the common "merge these fields into the profile" case, use client.profiles.create(userId, { profile }) (POST, deep-merge).
• client.profiles.replace(userId, { profile }) — this DOES exist and is a full PUT that overwrites the profile. Use it only when you need to reset a profile to a known-good state. For everyday writes, client.profiles.create (merge) is safer because it won't silently drop fields.

Universal Rules

• NEVER batch or delay OTP, password reset, or security alert notifications
• Use idempotency keys for sends where duplicates would be harmful (payments, security alerts, OTPs)
• NEVER expose full email/phone in security change notifications (mask them)
• ALWAYS include "I didn't request this" links in security-related emails
• ALWAYS use E.164 format for phone numbers
• Only send to channels the user has asked for or that make sense for the use case — don't blast every channel by default
• For template sends, use Courier-generated nt_... IDs as canonical; treat IDs as opaque workspace-specific values and resolve aliases to nt_... before sending

See also (not duplicated here)

• Quiet hours (non-OTP, non-security): [resources/guides/patterns.md](./resources/guides/patterns.md) and [resources/guides/throttling.md](./resources/guides/throttling.md)
• 429 / provider rate limits and retries: [resources/guides/throttling.md](./resources/guides/throttling.md) and [resources/guides/reliability.md](./resources/guides/reliability.md)
• Compliance (GDPR, CAN-SPAM, TCPA, 10DLC): app-layer concern — see channel guides ([resources/channels/email.md](./resources/channels/email.md), [resources/channels/sms.md](./resources/channels/sms.md)) for sender-auth and opt-in mechanics; consult legal counsel for jurisdictional requirements
• Test vs. production workspaces and safe deploys: [resources/guides/quickstart.md](./resources/guides/quickstart.md) (API keys per environment) and [resources/guides/reliability.md](./resources/guides/reliability.md)

Courier Inbox Version Detection

Before providing Inbox guidance, determine which SDK version the user is on:

1. Check for v7 indicators — Look for any of: @trycourier/react-provider, @trycourier/react-inbox, @trycourier/react-toast, @trycourier/react-hooks, `, useInbox(), useToast(), (not ), clientKey prop, renderMessage prop. Check package.json` if available.
2. Check for v8 indicators — Look for any of: @trycourier/courier-react, @trycourier/courier-react-17, @trycourier/courier-ui-inbox, useCourier(), `, , courier.shared.signIn(), registerFeeds, listenForUpdates`.
3. If unclear, ask — "Which version of the Courier Inbox SDK are you using? If you have @trycourier/react-inbox in your package.json, that's v7. If you have @trycourier/courier-react, that's v8."

ALWAYS use v8 for new projects — v7 is legacy. If the user is on v7:

• Do NOT write new v7 code. The correct path is to upgrade to v8.
• Read [resources/channels/inbox-v7-legacy.md](./resources/channels/inbox-v7-legacy.md) before touching v7 code — it documents recognition patterns and the migration path.
• Guide them to migrate using the step-by-step guide: https://www.courier.com/docs/sdk-libraries/courier-react-v8-migration-guide
• v8 is a smaller bundle, has no third-party dependencies, built-in dark mode, and a modern UI.
• The v7 and v8 APIs are completely different — v7 code will not work with v8 and vice versa.
• Only exception: v8 does not yet support Tags or Pins. If the user depends on those, they may need to stay on v7 temporarily, but should plan to migrate once v8 adds support.

Official Courier Documentation

When you need current API signatures, SDK methods, or features not covered in these resources:

1. Fetch https://www.courier.com/docs/llms.txt — returns a structured markdown index of all Courier documentation pages with URLs and descriptions
2. Scan the index for the relevant page, then fetch that page's URL for full details
3. Prefer the patterns in THIS skill for best practices; use llms.txt for API specifics

When to use llms.txt:

• You need the exact signature for a method not shown in these resources (e.g., client.audiences.create())
• A developer asks about a Courier feature this skill doesn't cover (e.g., Audiences, Brands, Translations)
• You need to verify that a code example in this skill match

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trycourier
• Source: trycourier/courier-skills
• License: MIT

Install and usage instructions live in the source repository linked above.