email

事务性电子邮件运营（SendGrid）

使用此技能通过 Twilio SendGrid 发送事务性电子邮件，并诊断送达问题：退信、垃圾邮件投诉和签名事件 Webhook。这是面向单一供应商（SendGrid）的工具技能。营销活动、模板构建器和其他服务商均不在范围内；此技能负责应用触发邮件的运营闭环：发送邮件、检查邮件是否送达，并验证相关事件确实可信。

运营约定

1. 执行任何变更前，先进行只读检查。 可随时检查送达情况信号（退信、垃圾邮件举报）。随附的 email-cli 脚本执行读取操作时不会写入任何内容。
2. 采取操作前，确认目标、范围和回滚方案。 发送邮件会以组织名义将内容放入收件人的收件箱：必须有明确的人类指令，指定收件人、发件人和内容；还必须通过 email-cli 使用 --dry-run 预览并使用 --yes 确认。邮件送达后无法可靠地“撤回”。
3. 遵守读取范围限制。 抑制列表使用 --limit 限制结果；切勿翻页查看超出任务所需的内容。
4. 信任 Webhook 前先进行验证。 SendGrid 的签名事件 Webhook 会对每个请求签名；在处理事件数据前，先验证 ECDSA 签名和时间戳。未经验证的 Webhook 端点会接受伪造的送达和退信事件。
5. 证据范围要有限。 引用简短的邮件预览和电子邮件地址；切勿在聊天中粘贴 API 密钥、完整邮件正文或抑制列表。
6. 没有明确指令时，切勿向未经验证的地址或真实用户发送邮件。 读取送达情况以进行问题排查是安全的；发送操作始终受此限制。

email-cli 脚本

scripts/email-cli 是面向 Agent、仅依赖标准库的 SendGrid v3 API 命令行工具，内置独立的 ECDSA P-256 签名验证器，无需第三方加密依赖。

email/scripts/email-cli --help                              # no key or network needed
email/scripts/email-cli --json --limit 20 deliverability bounces
email/scripts/email-cli --json --limit 20 deliverability spam-reports
email/scripts/email-cli send --to [email protected] --from [email protected] \
  --subject "Password reset" --body "..." --dry-run          # preview only
email/scripts/email-cli send --to [email protected] --from [email protected] \
  --subject "Password reset" --body "..." --yes              # confirmed send
email/scripts/email-cli webhook verify --body-file body.json \
  --signature "MEUC..." --timestamp 1712345678 --public-key-file public-key.pem

退出代码：0 表示成功，1 表示 API 错误或验证失败，2 表示用法错误。发送操作受保护：未指定 --dry-run 或 --yes 时，脚本会拒绝操作并以退出代码 1 退出，且不会调用 API。读取操作受 --limit 限制（默认值为 20，最大值为 100）。

运营流程

1. 明确送达问题的范围：这是发送邮件（变更），还是调查送达问题（读取）？发件人是谁，收件人是谁，邮件内容是什么？
2. 在范围内读取：使用 deliverability bounces 和 deliverability spam-reports 查看哪些邮件未能送达及其原因。
3. 分析信号：根据证据判断原因（硬退信 → 地址错误或拼写错误；垃圾邮件投诉 → 内容或发送频率问题；抑制列表 → 先前发生过退信）。检查 SendGrid 的事件 Webhook 负载，查看送达/退信事件——先验证签名。
4. 经确认后操作：只有在收到人类发送指令，并使用 --dry-run 预览、使用 --yes 确认后，才能发送。
5. 验证：确认发送响应（x-message-id），之后再根据 Webhook/API 证据确认送达，不要想当然地宣称成功。

发送事务性电子邮件

• 撰写邮件：已验证的发件人（from）、一个或多个收件人（to）、subject、纯文本 body，以及可选的 html 正文。SendGrid 要求发件地址是你账户中已验证的发件人身份。
• 发送前预览：--dry-run 会显示发件人、收件人、主题和正文的完整预览，且绝不会调用 API。--yes 表示确认并向 POST /v3/mail/send 发送请求；该请求会返回带有 x-message-id 标头的 202 Accepted。
• 切勿通过电子邮件发送机密或令牌。 电子邮件可能导致信息泄露；发送密码重置链接可以，但不能发送原始凭据。
• SendGrid 返回 202（已接受）——接受不代表送达。在声称发送成功前，先通过事件 Webhook 或活动动态确认送达。

投递能力检查

• 退信（GET /suppression/bounces）：邮件退回的收件人，以及退信原因和状态。硬退信（永久性 5.x.x）表示地址无效；反复退信会损害发件人信誉。
• 垃圾邮件举报（GET /suppression/spam_reports）：将邮件标记为垃圾邮件的收件人。频繁投诉表明内容或目标受众存在问题。
• 投递能力排查为只读操作：根据抑制列表和 Webhook 事件进行诊断，之后只有在获得确认的情况下，才更改下一次发送内容（属于变更操作）。

Webhook 签名验证

SendGrid 的 Signed Event Webhook 使用 ECDSA 密钥对为每个请求签名。验证步骤如下：

1. 获取完全未经处理的原始请求正文字节 — 任何重新编码都会破坏签名。
2. 检查 X-Twilio-Email-Event-Webhook-Timestamp 是否为近期时间戳（用于防止重放；email-cli 的默认时间窗口为 300s，可通过 --max-age 0 禁用）。
3. 对 timestamp + raw body 计算 SHA-256（按字节拼接，不加分隔符），并使用 Webhook 公钥验证 ECDSA P-256 签名（X-Twilio-Email-Event-Webhook-Signature，经 base64 解码后的 ASN.1 DER 格式）。
4. 如果时间戳已过期或签名验证失败，则返回 401。

email-cli webhook verify --body-file body.json --signature <header> --timestamp <header> --public-key-file public-key.pem 会使用仅依赖标准库的 P-256 实现执行完全相同的检查。启用 Signed Webhook 后，可在 Event Webhook 设置中查看公钥；请将其存储为文件，切勿写入代码。

参考资料路由

加载时机	参考资料
来源、刷新流程	references/00-source-index.md
API 范围、Webhook 验证详情、投递能力语义	references/01-sendgrid-operations.md

包含的文件

• scripts/email-cli：范围受限、仅依赖标准库的 CLI（发送、投递能力退信/垃圾邮件举报、使用自包含 ECDSA P-256 实现进行 Webhook 验证；--json；--limit；发送操作需通过 --dry-run/--yes 控制）。
• tests/test_email_cli.py：针对 SendGrid API 存根的 15 项确定性测试，以及由 OpenSSL 生成的 ECDSA Webhook 测试向量（用于独立交叉验证验证器）。
• references/：带日期的来源索引和 SendGrid 操作参考。
• evals/evals.json：用于评估 Agent 运行输出质量的六个用例。

验证边界

声明	最低证据
消息已被接受	email-cli send --yes 以状态码 0 退出，并返回 x-message-id
收件人发生退信	email-cli deliverability bounces --json 列出该地址及其原因和状态
Webhook 真实可信	对准确的正文/签名/时间戳运行 email-cli webhook verify，以状态码 0 退出且返回 verified: true
邮件确已送达	经验证的 Delivery Webhook 事件，或 activity feed 显示该消息已送达

严格限制

• 未经人工指示、--dry-run 预览和 --yes 确认，绝不发送邮件 — 已发送的邮件无法撤回，会发送到外部收件人的收件箱。
• 未验证 ECDSA 签名和时间戳时，绝不信任传入的 Webhook。
• 查询不得超过 --limit；绝不将完整邮件正文、API 密钥或抑制列表完整内容输出到聊天中。
• 此技能仅涵盖 SendGrid 事务性邮件。营销活动、模板系统和其他服务提供商均不在范围内。

不适用情形

• 营销或群发邮件活动（SendGrid Marketing Campaigns、用户细分、批量发送）— 这是具有独立工具链的不同产品功能。
• 其他邮件服务提供商（Postmark、SES、Mailgun、Resend）— 每家都有自己的 API；此技能仅涵盖 SendGrid。
• 设计组织规模的邮件投递能力策略或域名信誉政策 — 这是运营政策工作；此技能用于操作 SendGrid 功能。
• 在应用程序中开发邮件功能（模板渲染、事务流程）— 这是应用开发；请参阅 后端工程。