前言¶
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。
