name: courier-notification-skills description: Use when building notifications across email, SMS, push, in-app, Slack, Teams, or WhatsApp. Covers transactional messages (password reset, OTP, orders, billing), growth notifications (onboarding, engagement, referral), multi-channel routing, compliance (GDPR, TCPA, CAN-SPAM), and reliability patterns.

Courier Notification Skills

Guidance for building deliverable, compliant, 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, compliance, 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.

Universal Rules (Never Violate)

• NEVER send promotional content in transactional notifications (CAN-SPAM violation)
• NEVER batch or delay OTP, password reset, or security alert notifications
• NEVER send SMS without TCPA-compliant consent records
• NEVER skip idempotency keys for transactional sends
• NEVER send during quiet hours (10pm-8am local) unless critical/security
• 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
• ALWAYS configure SPF + DKIM + DMARC before sending production email
• ALWAYS respect user opt-out preferences immediately
• ALWAYS use method: "single" unless the notification is critical enough to warrant all channels

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 index of all Courier documentation
2. Use it to find specific endpoint details, SDK method signatures, and configuration options
3. Prefer the patterns in THIS skill for best practices; use llms.txt for API specifics

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

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.

• Compliance concerns (GDPR, TCPA, CAN-SPAM) → Read Compliance, then channel-specific rules in SMS or Email.

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

• Migrating or building with Courier React SDK (Inbox, Toast, hooks) → Read React SDK Migration. If the inbox renders but shows no messages, this is almost certainly a v7/v8 mixing issue.

• Debugging delivery issues → Use the CLI to inspect messages and delivery history. Email going to spam? Email. SMS not arriving? SMS. General failures? Reliability.

• Ad-hoc operations, CI/CD, or AI agent workflows → See CLI for installation, commands, and zero-config agent patterns.

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