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

| Need to... | See | |------------|-----| | Send emails, fix deliverability, set up SPF/DKIM/DMARC | Email | | Send SMS, handle TCPA/10DLC compliance | SMS | | Send push notifications, handle iOS/Android differences | Push | | Build in-app notification center | Inbox | | Send Slack messages with Block Kit | Slack | | Send Microsoft Teams messages | MS Teams | | Send WhatsApp messages with templates | 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 | |------------|-----| | Route across multiple channels, set up fallbacks | Multi-Channel | | Manage user notification preferences | Preferences | | Ensure GDPR, TCPA, CAN-SPAM compliance | Compliance | | Handle retries, idempotency, error recovery | Reliability | | Combine notifications, build digests | Batching | | Control frequency, prevent fatigue | Throttling | | Plan notifications for your app type | Catalog | | Reusable code patterns (consent, quiet hours, masking, retry) | Patterns |

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, compliance.md | | SMS setup & compliance | sms.md (includes 10DLC, TCPA) | | Push notification setup | push.md | | In-app inbox setup | inbox.md | | Onboarding sequence | onboarding.md, multi-channel.md | | Security alerts | authentication.md, multi-channel.md | | Digest/batching | batching.md, preferences.md | | Payment/billing notifications | billing.md, reliability.md | | Appointment reminders | appointments.md, sms.md | | WhatsApp templates | whatsapp.md | | Slack/Teams integration | slack.md or ms-teams.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.

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

• Debugging delivery issues → Email going to spam? Email. SMS not arriving? SMS. General failures? Reliability.

• Reusable code patterns (consent check, quiet hours, idempotency, fallback) → See Patterns for copy-paste implementations.