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, <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](./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](./resources/channels/email.md) | | 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](./resources/channels/sms.md) | | 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](./resources/channels/push.md) | | 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)](./resources/channels/inbox.md) — v8 primary. If you have existing v7 code (@trycourier/react-inbox, <CourierProvider>, useInbox), see [Inbox v7 legacy](./resources/channels/inbox-v7-legacy.md) 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](./resources/channels/slack.md) | | 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](./resources/channels/ms-teams.md) | | 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](./resources/channels/whatsapp.md) |

By Transactional Type

| Need to... | See | |------------|-----| | Build password reset, OTP, verification, security alerts | [Authentication](./resources/transactional/authentication.md) | | Build order confirmations, shipping, delivery updates | [Orders](./resources/transactional/orders.md) | | Build receipts, invoices, dunning, subscription notices | [Billing](./resources/transactional/billing.md) | | Build booking confirmations, reminders, rescheduling | [Appointments](./resources/transactional/appointments.md) | | Build welcome messages, profile updates, settings changes | [Account](./resources/transactional/account.md) | | Understand transactional notification principles | [Transactional Overview](./resources/transactional/index.md) |

By Growth Type

| Need to... | See | |------------|-----| | Build activation flows, setup guidance, first value | [Onboarding](./resources/growth/onboarding.md) | | Build feature announcements, discovery, education | [Adoption](./resources/growth/adoption.md) | | Build activity notifications, retention, habit loops | [Engagement](./resources/growth/engagement.md) | | Build winback, inactivity, cart abandonment | [Re-engagement](./resources/growth/reengagement.md) | | Build referral invites, rewards, viral loops | [Referral](./resources/growth/referral.md) | | Build promotions, sales, upgrade campaigns | [Campaigns](./resources/growth/campaigns.md) | | Understand growth notification principles | [Growth Overview](./resources/growth/index.md) |

Cross-Cutting Guides

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

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

Decision Guide

What are you building?

• A specific notification (OTP, order confirm, password reset, etc.) → Use the [Minimal File Sets](#minimal-file-sets-by-task) table above to find exactly which 1-2 files to read.

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

• Multi-step notification sequences (onboarding drips, escalations, reminder ladders, cart abandonment, win-back) → Start with [Journeys](./resources/guides/journeys.md). 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](#cross-cutting-guides) for the relevant guide.

• Planning which notifications to build for a new app → Start with [Catalog](./resources/guides/catalog.md), then [Email](./resources/channels/email.md), then [Multi-Channel](./resources/guides/multi-channel.md).

• Growth / lifecycle notifications (onboarding, engagement, referral) → Read [Growth Overview](./resources/growth/index.md) for consent requirements first, then the specific type.

• New to Courier or sending your first notification → Start with [Quickstart](./resources/guides/quickstart.md).

• Debugging delivery issues → Always start with [CLI](./resources/guides/cli.md) (courier messages list, courier messages content) to see the real delivery state before guessing. Then: email going to spam? [Email](./resources/channels/email.md). SMS not arriving? [SMS](./resources/channels/sms.md). General failures? [Reliability](./resources/guides/reliability.md).

• 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](./resources/guides/mcp.md). Use CLI for shell-only environments, CI/CD, or when MCP isn't available — see [CLI](./resources/guides/cli.md). 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](./resources/guides/templates.md) for the full CRUD lifecycle (create, publish, version, localize). See [Elemental](./resources/guides/elemental.md) 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](./resources/guides/patterns.md) for copy-paste implementations in TypeScript, Python, CLI, and curl.

• Migrating from another notification system to Courier → From Knock: [Migrate from Knock](./resources/guides/migrate-from-knock.md). From Novu: [Migrate from Novu](./resources/guides/migrate-from-novu.md). From any other system (custom-built, SendGrid direct, Twilio direct, etc.): [General Migration](./resources/guides/migrate-general.md).