前言¶
SaaS 产品几乎都要发通知：注册确认、订单回执、安全告警、营销触达，渠道往往不止邮件，还有 SMS、Push、应用内收件箱、Slack、Teams 等。自己接各厂商 SDK、对照文档改 payload，再处理偏好、路由和投递失败排查，耗在集成和踩坑上的时间很长。Courier 把发送、模板、路由和用户偏好收在统一 API 里；官方仓库 trycourier/courier-skills 里的 courier Skill，则是把这套能力写成 Agent 可遵循的知识包，让编码助手按正确 primitive 和 SDK 形态生成代码，而不是凭记忆拼接口。
这是什么¶
courier 是 Courier 官方维护的 Agent Skill（MIT 许可），面向「用 Courier 做通知」的全流程：发送、模板、翻译、路由、偏好、Journeys、CLI 与 MCP 等。Skill 的 description 写明适用场景：在邮件、SMS、Push、应用内收件箱、Slack、Teams、WhatsApp 等渠道上构建通知，并覆盖投递调试。
底层产品 Courier 是通知 BaaS：一次 send 面向用户（或列表、受众、租户），内容来自模板或内联字段，由路由选渠道、由偏好过滤，再由 Courier 渲染并投递；带延迟、分支或聚合的多步流程用 Journeys（JSON 定义，API 触发）。
核心功能¶
下面介绍 Skill 文档里强调、且与官方仓库说明一致的能力边界。
统一发送模型¶
- 收件人：
message.to支持user_id、内联email/phone_number、list_id、list_pattern、audience_id，或上述形式的数组；单次to数组硬上限 500，超出需用列表、受众或 Bulk API。 - 多租户：通过
to.tenant_id或message.context.tenant_id携带租户，加载该租户的品牌与偏好默认值。 - SDK 形态：Node 使用
@trycourier/courier，Python 使用trycourier；默认从环境变量COURIER_API_KEY读取密钥。发送入口为client.send.message，支持Idempotency-Key头。
渠道与场景¶
Skill 覆盖邮件（可达性、SPF/DKIM/DMARC）、SMS（10DLC 等）、Push（APNs/FCM）、应用内 Inbox（JWT、各端 SDK）、Slack、Microsoft Teams、WhatsApp 等，均经同一 send 形状，具体渠道由路由与用户资料决定。
文档区分 Transactional（密码重置、OTP、订单等，不应批量或延迟）与 Lifecycle marketing（需记录 opt-in 的主动触达），并映射到对应 Courier primitive。
平台能力¶
参考资料目录包含：Journeys、模板与 Elemental、多语言翻译、路由策略、用户/工作区偏好、摘要（digest）、受众与列表、品牌与租户、可靠性（幂等、重试、状态）、双向 Webhook、Bulk 发送、提供商配置等。
SDK 面与工具¶
Skill 列出 23 个命名空间作为完整 SDK 表面（如 send、journeys、lists、users、routingStrategies 等），并约定以已安装 SDK 的类型为 ground truth，而非凭记忆写形状。
配套 Courier CLI 用于投递排查（例如按 requestId 查消息列表、按 message-id 看 history 与 content）；仓库还提到 Courier MCP（API 与文档服务），Claude Code 插件可自带 docs MCP。
Agent 使用约定¶
Skill 要求助手：先路由到 1～2 个任务相关文件，不要通读整棵树；请求含糊时追问渠道、事务/生命周期、语言等；形状以 live source / 已装 SDK 核对；遵守 Universal Rules（幂等、E.164 手机号、不默认全渠道轰炸、模板 ID 使用 nt_... 等形式）。
安装与启用¶
通用方式（资料写明适用于 Claude Code、Cursor、Codex 等支持 Agent Skills 的工具）：
npx skills add trycourier/courier-skills
Claude Code 可选用插件（自更新并附带 Courier docs MCP）：
/plugin marketplace add trycourier/courier-skills
/plugin install courier@courier-skills
更新插件：
/plugin update courier@courier-skills
手动安装（任意能读取 skills 目录的工具）：克隆仓库后，将 skills/courier 复制到 ~/.cursor/skills/ 或 ~/.claude/skills/。发现机制依赖 SKILL.md frontmatter 中的 name 与 description，无需额外配置。
应用侧若已安装 @trycourier/courier 或 trycourier，Skill 会跳过 quickstart 中的安装步骤并假定已有 client。
典型用法¶
30 秒发送示例（Node）¶
先配置 COURIER_API_KEY，再按 canonical 形状调用：
import Courier from "@trycourier/courier";
const client = new Courier(); // reads COURIER_API_KEY from the environment
await client.send.message({
message: {
to: { user_id: "user-123" },
template: "welcome-email", // or inline content: { title, body }
data: { name: "Alice" },
},
});
同一结构可发往邮件、SMS、Push、Slack、Teams、WhatsApp 或应用内渠道，不由不同 API 区分。
Python 等价调用¶
from courier import Courier
client = Courier()
client.send.message(
message={
"to": {"user_id": "user-123"},
"template": "nt_01kmrbq6ypf25tsge12qek41r0",
"data": {},
},
extra_headers={"Idempotency-Key": "order-confirmation-12345"},
)
投递失败排查（CLI 阶梯）¶
单条消息失败时，资料建议按顺序执行：
send返回2xx且带有requestId，才表示 Courier 已接受请求。courier messages list --trace-id "<requestId>"查看 Courier 侧结果（列表/受众发送会扇出为多条 message）。courier messages history --message-id "<id>"看事件时间线。courier messages content --message-id "<id>"核对实际渲染内容。- 再按渠道查邮件/SMS 等专项指南与可靠性文档。
用自然语言向助手提问时，仓库 README 举例包括：欢迎邮件、send + 模板、Inbox 集成、按主题做 digest、Push 失败回退邮件、偏好中心、受众分段、多租户品牌、OTP 与订单回执（幂等）、多日 onboarding Journey 等；Skill 会把请求路由到对应参考文件并生成 TypeScript、Python、CLI 或 curl。
适用场景与注意¶
适合谁：做 SaaS、电商、市场或移动应用的开发者；希望把邮件、SMS、Push、聊天等提供商收敛到单一通知 API 的团队；需要偏好中心、退订、多渠道路由或配合 AI 助手写 Courier 集成的人。
使用注意：
- 对支付、安全告警、OTP 等重复发送有害的场景，应使用 Idempotency-Key。
- 营销类通知需遵守 opt-in 等规则；事务类通知不应被批量或延迟处理。
- 超过 500 个临时收件人不要用
to大数组，应改用列表、受众或 Bulk。 - 单条投递问题走 CLI 阶梯；模板整体送达率下降应查 metrics 类指南，而不是只对样本跑阶梯。
- 安静时段与定时投递、429 与限流、测试/生产工作区与 API Key 分离等细节在 Skill 引用的专项 guide 中，本文不重复展开。
结尾¶
courier Skill 把 Courier 的通知模型、SDK 形状、渠道规则与排障流程打包成 Agent 可读的知识库，降低「接通知」在文档往返和接口形状上的集成成本。官方 Skill 目录与说明见：
https://github.com/trycourier/courier-skills/tree/main/skills/courier
安装入口与更多示例见仓库根目录 README：npx skills add trycourier/courier-skills。
