courier-notification-skills

name

courier-notification-skills

description

Use when building notifications with Courier across email, SMS, push, in-app inbox, Slack, Teams, or WhatsApp. Covers transactional messages (password reset, OTP, orders, billing), growth notifications (onboarding, engagement, referral), multi-channel routing, preferences and topics, reliability and webhooks, journeys (multi-step notification sequences via API), template CRUD and Elemental content, routing strategies, provider configuration, the Courier CLI and MCP server, and migrations from Knock, Novu, or other notification systems.

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 + 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

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, templates.md, routing-strategies.md, and 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.

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 and resources/guides/throttling.md
• 429 / provider rate limits and retries: resources/guides/throttling.md and resources/guides/reliability.md
• Compliance (GDPR, CAN-SPAM, TCPA, 10DLC): app-layer concern — see channel guides (resources/channels/email.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 (API keys per environment) and 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, <CourierProvider>, useInbox(), useToast(), <Inbox /> (not <CourierInbox />), 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(), <CourierInbox />, <CourierToast />, 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 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 matches the current SDK version

When NOT to use llms.txt:

• The answer is already in these resource files (prefer this skill's opinionated patterns over raw docs)
• The question is about best practices or notification design (llms.txt won't help)

Architecture Overview

[User Action / System Event]
            │
            ▼
    ┌───────────────┐
    │ Notification  │
    │   Trigger     │
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │   Routing     │──── User Preferences
    │   Decision    │──── Channel Availability
    └───────┬───────┘──── Urgency Level
            │
            ▼
    ┌───────────────────────────────────────┐
    │           Channel Selection           │
    ├───────┬───────┬───────┬───────┬──────┤
    │ Email │  SMS  │ Push  │ Inbox │ Chat │
    └───┬───┴───┬───┴───┬───┴───┬───┴───┬──┘
        │       │       │       │       │
        ▼       ▼       ▼       ▼       ▼
    [Delivery] [Delivery] [Delivery] [Delivery] [Delivery]
        │       │       │       │       │
        └───────┴───────┴───────┴───────┘
                        │
                        ▼
                ┌───────────────┐
                │   Webhooks    │
                │   & Events    │
                └───────────────┘

Quick Reference

By Channel

Need to...	Pick when...	See
Send emails, fix deliverability, set up SPF/DKIM/DMARC	You need a durable, detailed record. Receipts, confirmations, long-form content, attachments, rich formatting. Deliverability depends on sender reputation (SPF/DKIM/DMARC); not real-time.	Email
Send SMS, handle 10DLC registration	You need reach and speed for short, time-sensitive messages. OTP, appointment reminders, shipping updates. 10DLC registration required in US; small character budget; per-message cost.	SMS
Send push notifications, handle iOS/Android differences	You need to nudge an engaged app user. Activity notifications, real-time alerts, re-engagement. Requires device token + OS permission; iOS and Android permission models differ; silent for users who disabled permission.	Push
Build in-app notification center	You need persistent, in-app notifications with read state, cross-device sync, and an inbox UI. Only visible in-app. Requires the Courier Inbox SDK (v7 vs v8 matters — see the file's header and the Inbox Version Detection section above).	Inbox (v8) — v8 primary. If you have existing v7 code (@trycourier/react-inbox, <CourierProvider>, useInbox), see Inbox v7 legacy before touching it.
Send Slack messages with Block Kit	The recipient is a Slack user or channel. Internal alerts, team notifications, chatops. Requires OAuth + bot setup; Block Kit has its own JSON shape; rate-limited per workspace.	Slack
Send Microsoft Teams messages	The recipient uses Microsoft Teams. Same use cases as Slack, different org. Requires connector or bot; Adaptive Cards have their own shape.	MS Teams
Send WhatsApp messages with templates	Regulated markets, customer support, high-engagement regions (LATAM, EU, IN). Rich media + templates. Approved Message Templates required outside the 24-hour customer service window; per-conversation pricing by category.	WhatsApp

By Transactional Type

Need to...	See
Build password reset, OTP, verification, security alerts	Authentication
Build order confirmations, shipping, delivery updates	Orders
Build receipts, invoices, dunning, subscription notices	Billing
Build booking confirmations, reminders, rescheduling	Appointments
Build welcome messages, profile updates, settings changes	Account
Understand transactional notification principles	Transactional Overview

By Growth Type

Need to...	See
Build activation flows, setup guidance, first value	Onboarding
Build feature announcements, discovery, education	Adoption
Build activity notifications, retention, habit loops	Engagement
Build winback, inactivity, cart abandonment	Re-engagement
Build referral invites, rewards, viral loops	Referral
Build promotions, sales, upgrade campaigns	Campaigns
Understand growth notification principles	Growth Overview

Cross-Cutting Guides

Need to...	See
Get started sending your first notification	Quickstart
Route across multiple channels, set up fallbacks	Multi-Channel
Manage user notification preferences	Preferences
Handle retries, idempotency, error recovery	Reliability
Combine notifications, build digests	Batching
Control frequency, prevent fatigue	Throttling
Plan notifications for your app type	Catalog
Use the CLI for ad-hoc operations, debugging, agent workflows	CLI
Use the MCP Server for structured API access from AI agents	MCP Server
Manage templates via API (create, publish, version)	Templates
Create routing strategies via API (rs_..., provider priority)	Routing Strategies
Configure providers via API (SendGrid, Twilio, etc., catalog discovery)	Providers
Understand Elemental content format (element types, control flow, localization)	Elemental
Build multi-step notification journeys (delays, branches, sequences)	Journeys
Reusable code patterns (consent, quiet hours, masking, retry)	Patterns
Migrate from any notification system to Courier	General Migration
Migrate from Knock to Courier	Migrate from Knock
Migrate from Novu to Courier	Migrate from Novu

Topics Not Covered In Depth (fetch from official docs)

The skill does not (yet) have dedicated guides for these areas. Fetch the page below via WebFetch when the user asks about them; do not invent API shapes from memory. When in doubt, fetch https://www.courier.com/docs/llms.txt first and use the URL it returns.

Topic	Fetch
Audiences (attribute-based targeting)	https://www.courier.com/docs/platform/users/audiences
Automations (legacy dashboard workflows — for new multi-step flows, use Journeys)	https://www.courier.com/docs/automations/overview
Brands (logos, colors, reusable visual identity)	https://www.courier.com/docs/platform/content/brands
Tenants (multi-tenant B2B, per-tenant branding/preferences)	https://www.courier.com/docs/platform/tenants/tenants-overview (also see Patterns "Tenants" section for code)
Events / event mapping	https://www.courier.com/docs/platform/automations/inbound-events (plus the event field on Send API)
Translations / i18n (beyond the per-template locales block)	https://www.courier.com/docs/platform/content/elemental/locales (element-level) or https://www.courier.com/docs/api-reference/translations/get-a-translation (API)

Minimal File Sets by Task

For common tasks, you only need to read these specific files:

Task	Files to Read
OTP/2FA implementation	authentication.md, sms.md
Password reset	authentication.md, email.md
Order notifications	orders.md, multi-channel.md
Email setup & deliverability	email.md
SMS setup	sms.md (includes 10DLC)
Push notification setup	push.md
In-app inbox setup	inbox.md — v8 primary; see inbox-v7-legacy.md only for existing v7 code
Onboarding sequence	onboarding.md, journeys.md
Security alerts	authentication.md, multi-channel.md
Digest/batching	batching.md, preferences.md
Payment/billing notifications	billing.md, reliability.md
Trial ending / subscription renewal reminder	billing.md (Trial Ending Journey), journeys.md
Appointment reminders	appointments.md, journeys.md
WhatsApp templates	whatsapp.md
Slack/Teams integration	slack.md or ms-teams.md
New to Courier / first notification	quickstart.md
CLI debugging / ad-hoc operations	cli.md
SMS delivery debugging	cli.md, sms.md
Email deliverability debugging	cli.md, email.md
General delivery failures	cli.md, reliability.md
MCP Server setup	mcp.md, cli.md
Migrating from any system	migrate-general.md, quickstart.md
Migrating from Knock	migrate-from-knock.md, quickstart.md
Migrating from Novu	migrate-from-novu.md, quickstart.md
Template CRUD / programmatic templates	templates.md, patterns.md
Create routing strategy programmatically	routing-strategies.md, templates.md
Configure a provider via API (SendGrid/Twilio/etc.)	providers.md, multi-channel.md
Elemental content format (element types, control flow)	elemental.md
Inline vs templated sending	templates.md, quickstart.md
Lists, bulk sends, multi-tenant	patterns.md
Provider failover setup	multi-channel.md
Webhook setup & signature verification	reliability.md
Preference topics and opt-out	preferences.md
Inbox JWT auth and React setup	inbox.md — v8 primary; see inbox-v7-legacy.md only for existing v7 code
Understanding to field / addressing	quickstart.md
Building multi-channel notifications	multi-channel.md, preferences.md
Making sends reliable	reliability.md, patterns.md
Reducing notification fatigue	throttling.md, batching.md, preferences.md
Templates + multi-channel routing	templates.md, multi-channel.md
Build a multi-step journey programmatically	journeys.md, elemental.md
Cart abandonment sequence	reengagement.md, journeys.md
Appointment reminder ladder	appointments.md, journeys.md
Escalation (in-app → push → email)	multi-channel.md, journeys.md
Win-back / re-engagement sequence	reengagement.md, journeys.md

Decision Guide

What are you building?

• A specific notification (OTP, order confirm, password reset, etc.) → Use the Minimal File Sets table above to find exactly which 1-2 files to read.

• A new notification channel (email, SMS, push, Slack, etc.) → See By Channel for the channel-specific guide.

• Multi-step notification sequences (onboarding drips, escalations, reminder ladders, cart abandonment, win-back) → Start with Journeys. Journeys let you define the full DAG (delays, branches, sends) as code via the API.

• Notification infrastructure (routing, preferences, reliability, batching) → See Cross-Cutting Guides for the relevant guide.

• Planning which notifications to build for a new app → Start with Catalog, then Email, then Multi-Channel.

• Growth / lifecycle notifications (onboarding, engagement, referral) → Read Growth Overview for consent requirements first, then the specific type.

• New to Courier or sending your first notification → Start with Quickstart.

• Debugging delivery issues → Always start with CLI (courier messages list, courier messages content) to see the real delivery state before guessing. Then: email going to spam? Email. SMS not arriving? SMS. General failures? Reliability.

• Ad-hoc operations, CI/CD, or AI agent workflows → Use MCP if your editor supports it (Cursor, Claude Code, Claude Desktop, Windsurf, VSCode) — see MCP Server. Use CLI for shell-only environments, CI/CD, or when MCP isn't available — see CLI. Both use the same API key and cover the same API surface.

• Managing templates programmatically or understanding Elemental (Courier's JSON templating language) → See Templates for the full CRUD lifecycle (create, publish, version, localize). See Elemental for the element-by-element reference (text, action, image, meta, channel, group), control flow (if, loop, ref), and locale handling.

• Reusable code patterns (consent check, quiet hours, idempotency, fallback) → See Patterns for copy-paste implementations in TypeScript, Python, CLI, and curl.

• Migrating from another notification system to Courier → From Knock: Migrate from Knock. From Novu: Migrate from Novu. From any other system (custom-built, SendGrid direct, Twilio direct, etc.): General Migration.