用途 该技能用于在 PostHog 中搭建并发送事务性邮件。事务性邮件是由用户操作触发的单封邮件，例如密码重置邮件。用户先在 PostHog Workflows 中设计邮件模板，将模板设为事务性，然后由后端代码通过一次调用发送给一个收件人。完整指南位于 https://posthog.com/docs/workflows/transactional-emails.md。
主要能力
- 发送与互动数据：开启 engagement capture 后，发送、投递、打开、点击、退信等事件会记录到对应 person 上，与产品事件并列。
- 模板编辑与发布：在 PostHog 中编辑邮件，支持草稿与版本，发布无需部署。
- 抑制列表与状态查询：Workflows 与事务性邮件共用一个抑制列表；每次发送返回消息 ID，可据此查询状态。
- 状态值包括 queued、sent、failed、delivered、bounced、complained，失败或退信会附带原因；状态在发送后需数秒出现，保留 30 天。
使用前检查 需要确认 MCP 已注册 workflows-make-email-template-transactional-prepare 与 workflows-make-email-template-transactional-execute 两个工具（因需用户确认，注册为成对动作）。若缺失，可能是 MCP 连接缺少 hog_flow:write 权限，或项目尚未开启事务性邮件；不应使用其他工具绕过。
配置步骤
- 验证发件人：调用 integrations-list（kind 为 email），项目需有已验证域名的发件人；若可使用 integrations-email-create，可在对话内创建，展示 DNS 记录，解析后调用 integrations-email-verify-create。用户在其他服务商已使用的域名仍需配置 PostHog 的 DNS 记录。
- 品牌：先了解用户现有邮件样式（网站、现有模板 HTML 或截图），提取 logo、颜色、字体与语气；上传 logo 前可先查 media-images-list。
- 模板：使用 designing-email-templates 技能创建或更新模板。模板无法读取 person 属性，所有展示值均由发送时以 {{ variables.<name> }} 传入，需与用户约定变量名。
- 分类：事务性模板不能属于 marketing 消息分类，可用 message-categories-list 检查。
- 设为事务性：调用 prepare，向用户展示返回信息并等待输入 confirm，再调用 execute（携带 confirmation_hash 与 confirm），此操作不可撤销。若模板还用于其他邮件，应先复制再转换。对于登录验证码、重置链接等敏感内容，应提示用户在模板 API 标签页开启 Protect sensitive data。
- 互动事件：调用 workflows-sending-rules-get，若 capture_workflows_engagement_events 关闭（默认），则不会记录发送等事件；可用 workflows-sending-rules-update 开启，并说明这些事件会计入项目事件用量。
- API 密钥：用户在项目设置的项目密钥中创建 secret API key，Workflow 权限设为 Write；应存放在服务端环境变量中，不得粘贴到聊天或客户端代码。
- 测试：发送一封到用户自己的地址，检查状态，并分享模板链接以便在 Sends 标签页查看。
从代码发送 Node.js 与 Python 使用 SDK，其他语言使用 HTTP API。
- Node.js：posthog.emails.send({ to, templateId, templateData, distinctId, idempotencyKey })，返回 { data, error }，不抛异常；在客户端设置 secretKey。
- Python：posthog.emails.send(to=..., template_id=..., template_data=..., distinct_id=..., idempotency_key=...)，抛出 EmailError；在客户端设置 secret_key。
- 任意语言：POST https://<app host>/api/projects/@current/messaging/send/email/，Authorization: Bearer <project secret API key>，JSON 体包含 template_id、to、message_data、distinct_id。 需安装最新 SDK；若已安装版本没有 emails API，应升级或改用 HTTP API。
代码要点
- 复用应用已有的 PostHog 客户端并设置 secret key，不要每次发送都新建客户端，应用退出时关闭。
- 始终传入收件人的 distinct ID（与其产品事件一致），否则该发送会落在一个 distinct ID 为邮箱地址的 person 上。
- 幂等键按用途派生，如 password-reset:<reset request id>。PostHog 在邮件入队后记住该键 24 小时，窗口内重试不会重复发送；超过 24 小时的重试或队列重放会再次发送，若重试可能延迟至此，应用需自行记录已发送邮件。
- PostHog Cloud 上 SDK 自动确定 app host；反向代理或自托管需设置 appHost（Node.js）或 app_host（Python）。
- 仅发邮件的 posthog-node 客户端应设置 enableLocalEvaluation: false，因为纯发送密钥无法轮询特性标志定义；或给密钥增加特性标志读取权限。Python 客户端仅在求值标志时加载定义。
- 让 SDK 错误传到调用方，或按错误码分支（如 recipient_suppressed、quota_limited），不要包装成通用错误或匹配消息文本。
- 遇到 network_error 或 503 时，PostHog 可能已入队；应使用相同幂等键重试，不要为该邮件切换到其他服务商，以免收件人收到两次。
查询状态 发送返回消息 ID，可用 posthog.emails.get(id) 或 GET /api/projects/@current/messaging/emails/<message_id>/ 读取状态。SDK 不会对 not_found 重试，若发送后立即读取需自行等待并重试；状态缺失不代表邮件失败。应先处理读取错误，避免认证、权限或限流错误被掩盖。只有项目 secret API key 能读取状态，因此无法通过 MCP 读取，需在用户代码中或由用户执行。
限制与注意事项
- 邮件内容位于模板中，发送时传递模板 ID 与占位符值，而非主题和正文。
- 每次调用只发给一个收件人。
- 事务性邮件处于 beta 阶段，与其他工作流邮件一样计费并受配额限制。
- 事务性模板不能属于营销分类；设为事务性的操作不可撤销。
从其他服务商迁移 若用户目前使用其他服务商，可参考 references/moving-from-other-providers.md，其中将各服务商的发送调用映射到 PostHog，并列出切换前需检查的事项。