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"):

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, Stainless-generated):

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, Stainless-generated):

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 (generated SDKs — both SDKs follow the same structure, Node = camelCase, Python = snake_case):

The table above covers the most common operations. 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).

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(...).
• 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

By Transactional Type

By Growth Type

Cross-Cutting Guides

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.

Minimal File Sets by Task

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

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.
• 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.