email-gateway

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skill:email-gateway - Multi-Provider Email Gateway

skill:email-gateway - 多服务商邮件网关

Version: 1.0.0

版本：1.0.0

Purpose

用途

Generate production-ready email sending integrations for Cloudflare Workers and Node.js applications. This skill produces a unified email interface that abstracts provider-specific APIs (Resend, SendGrid, Mailgun, SMTP2Go), includes template rendering, error handling with retry logic, and delivery tracking via webhooks. Use this skill when a project needs transactional or notification email capabilities with provider flexibility.

为Cloudflare Workers和Node.js应用生成可用于生产环境的邮件发送集成。该skill提供统一的邮件接口，抽象了Resend、SendGrid、Mailgun、SMTP2Go等服务商的专属API，包含模板渲染、带重试逻辑的错误处理以及通过webhook实现的投递追踪功能。当项目需要具备服务商灵活性的事务性或通知类邮件能力时，可使用此skill。

File Structure

文件结构

skills/email-gateway/
├── SKILL.md (this file)
├── examples.md
├── scripts/ (optional)
│   └── [helper scripts]
└── templates/ (optional)
    └── [output templates]

skills/email-gateway/
├── SKILL.md (本文件)
├── examples.md
├── scripts/ (可选)
│   └── [辅助脚本]
└── templates/ (可选)
    └── [输出模板]

Interface References

接口参考

Context: Loaded via ContextProvider Interface
Memory: Accessed via MemoryStore Interface
Shared Patterns: Shared Loading Patterns
Schemas: Validated against context_metadata.schema.json and memory_entry.schema.json

Context：通过ContextProvider 接口加载
Memory：通过MemoryStore 接口访问
共享模式：共享加载模式
Schema：依据context_metadata.schema.json和memory_entry.schema.json进行验证

Mandatory Workflow

强制工作流

IMPORTANT: Execute ALL steps in order. Do not skip any step.

重要提示：按顺序执行所有步骤，请勿跳过任何步骤。

Step 1: Initial Analysis

步骤1：初始分析

Gather inputs: provider choice (Resend, SendGrid, Mailgun, SMTP2Go), target environment (Cloudflare Workers vs Node.js), template needs (plain text, HTML, React Email)
Detect project type: runtime, framework (Express, Hono, itty-router), existing email dependencies
Determine project name for memory lookup
Identify if multi-provider failover is required
Note any existing email infrastructure or provider accounts

收集输入信息：服务商选择（Resend、SendGrid、Mailgun、SMTP2Go）、目标环境（Cloudflare Workers 或 Node.js）、模板需求（纯文本、HTML、React Email）
检测项目类型：运行时、框架（Express、Hono、itty-router）、现有邮件依赖
确定用于内存查找的项目名称
判断是否需要多服务商故障转移
记录任何现有邮件基础设施或服务商账户信息

Step 2: Load Memory

步骤2：加载内存

Follow Standard Memory Loading with
skill="email-gateway"
and
domain="engineering"
.

Load
```
provider_config.md
```
— previous provider configurations, API key patterns, from-address conventions
Load
```
template_patterns.md
```
— previously used email templates, rendering approaches, design patterns

遵循标准内存加载流程，设置
skill="email-gateway"
和
domain="engineering"
。

加载
```
provider_config.md
```
—— 历史服务商配置、API密钥模式、发件地址约定
加载
```
template_patterns.md
```
—— 曾使用过的邮件模板、渲染方式、设计模式

Step 3: Load Context

步骤3：加载上下文

Follow Standard Context Loading for the
engineering
domain. Stay within the file budget declared in frontmatter.

Load relevant engineering context for the target runtime (Cloudflare Workers API, Node.js patterns)
Load API integration patterns if available

针对
engineering
域遵循标准上下文加载流程。请遵守前置声明中的文件预算限制。

加载目标运行时的相关工程上下文（Cloudflare Workers API、Node.js模式）
若有可用的API集成模式，一并加载

Step 4: Configure Provider

步骤4：配置服务商

Purpose: Set up the chosen email provider(s) with proper configuration

Actions:

Define API key management strategy (environment variables, secrets binding)
Configure provider endpoints and authentication:
- Resend:
```
https://api.resend.com/emails
```
  with Bearer token
- SendGrid:
```
https://api.sendgrid.com/v3/mail/send
```
  with Bearer token
- Mailgun:
```
https://api.mailgun.net/v3/{domain}/messages
```
  with Basic auth
- SMTP2Go:
```
https://api.smtp2go.com/v3/email/send
```
  with api-key header
Set default from addresses, reply-to addresses, and sender names
Configure provider-specific options (tracking, tags, metadata)
For multi-provider setups, define primary/fallback order and failover triggers

Output: Complete provider configuration ready for code generation

目的：通过恰当配置设置所选邮件服务商

操作：

定义API密钥管理策略（环境变量、密钥绑定）
配置服务商端点与认证：
- Resend：
```
https://api.resend.com/emails
```
  ，使用Bearer令牌
- SendGrid：
```
https://api.sendgrid.com/v3/mail/send
```
  ，使用Bearer令牌
- Mailgun：
```
https://api.mailgun.net/v3/{domain}/messages
```
  ，使用Basic认证
- SMTP2Go：
```
https://api.smtp2go.com/v3/email/send
```
  ，使用api-key请求头
设置默认发件地址、回复地址和发件人名称
配置服务商专属选项（追踪、标签、元数据）
若为多服务商配置，定义主服务商/备用服务商顺序以及故障转移触发条件

输出：可用于代码生成的完整服务商配置

Step 5: Generate Email Integration

步骤5：生成邮件集成代码

Purpose: Produce the email sending code with unified interface

Actions:

Generate unified email interface:
- ```
EmailMessage
```
  type (to, from, subject, html, text, cc, bcc, replyTo, attachments)
- ```
EmailResult
```
  type (id, provider, status, timestamp)
- ```
EmailProvider
```
  interface (send, sendBatch, validateAddress)
Generate provider adapter(s):
- Provider-specific API client implementing
```
EmailProvider
```
- Request/response mapping to unified types
- Authentication header construction
- Rate limit awareness per provider
Generate template rendering:
- HTML template rendering (string interpolation or React Email for Resend)
- Plain text fallback generation
- Template variable validation
- Reusable layout components (header, footer, button)
Generate error handling:
- Provider-specific error code mapping to unified error types
- Retry logic with exponential backoff for transient failures (429, 500, 502, 503)
- Non-retryable error identification (400, 401, 403, invalid recipient)
- Structured error logging
Generate retry logic:
- Configurable max retries and backoff multiplier
- Provider failover on persistent failure (if multi-provider)
- Dead letter handling for permanently failed sends

Output: Complete email integration module with all components

目的：生成具备统一接口的邮件发送代码

操作：

生成统一邮件接口：
- ```
EmailMessage
```
  类型（收件人、发件人、主题、HTML内容、纯文本内容、抄送、密送、回复地址、附件）
- ```
EmailResult
```
  类型（ID、服务商、状态、时间戳）
- ```
EmailProvider
```
  接口（发送、批量发送、验证地址）
生成服务商适配器：
- 实现
```
EmailProvider
```
  接口的服务商专属API客户端
- 请求/响应与统一类型的映射
- 认证头构建
- 服务商速率限制感知
生成模板渲染逻辑：
- HTML模板渲染（字符串插值或Resend专属的React Email）
- 纯文本备选内容生成
- 模板变量验证
- 可复用布局组件（页眉、页脚、按钮）
生成错误处理逻辑：
- 服务商专属错误码到统一错误类型的映射
- 针对临时故障（429、500、502、503）的指数退避重试逻辑
- 不可重试错误识别（400、401、403、无效收件人）
- 结构化错误日志
生成重试逻辑：
- 可配置的最大重试次数和退避乘数
- 若为多服务商配置，在持续故障时触发服务商故障转移
- 永久发送失败的死信处理

输出：包含所有组件的完整邮件集成模块

Step 6: Implement Delivery Tracking

步骤6：实现投递追踪

Purpose: Add webhook handling for email delivery lifecycle

Actions:

Generate webhook endpoint:
- Route handler for provider webhook callbacks
- Signature verification per provider (Resend uses svix, SendGrid uses event webhook signing, Mailgun uses signing key)
- Event payload parsing to unified delivery event type
Generate delivery status tracking:
- Event types: delivered, bounced, complained, opened, clicked, unsubscribed
- Status persistence strategy (KV store for Workers, database for Node.js)
- Bounce classification (hard bounce vs soft bounce)
Generate complaint handling:
- Automatic suppression list management
- Complaint notification to administrators
- Unsubscribe link generation and handling

Output: Webhook handlers and delivery tracking integration

目的：添加邮件投递生命周期的webhook处理逻辑

操作：

生成webhook端点：
- 服务商webhook回调的路由处理器
- 各服务商的签名验证（Resend使用svix，SendGrid使用事件webhook签名，Mailgun使用签名密钥）
- 将事件负载解析为统一的投递事件类型
生成投递状态追踪逻辑：
- 事件类型：已投递、已退回、已投诉、已打开、已点击、已取消订阅
- 状态持久化策略（Workers使用KV存储，Node.js使用数据库）
- 退回分类（硬退回 vs 软退回）
生成投诉处理逻辑：
- 自动抑制列表管理
- 向管理员发送投诉通知
- 取消订阅链接生成与处理

输出：webhook处理器与投递追踪集成代码

Step 7: Generate Output

步骤7：生成输出

Save output to

/claudedocs/email-gateway_{project}_{YYYY-MM-DD}.md

Follow naming conventions in
```
../OUTPUT_CONVENTIONS.md
```
Include: generated file manifest, configuration checklist, provider setup instructions, testing guide
Use templates from
```
templates/
```
directory if available

将输出保存到

/claudedocs/email-gateway_{project}_{YYYY-MM-DD}.md

遵循
```
../OUTPUT_CONVENTIONS.md
```
中的命名规范
包含内容：生成的文件清单、配置检查清单、服务商设置指南、测试指南
若有可用模板，使用
```
templates/
```
目录中的模板

Step 8: Update Memory

步骤8：更新内存

Follow Standard Memory Update for
skill="email-gateway"
. Store any newly learned patterns, conventions, or project insights.

Update
```
provider_config.md
```
with provider choices, configuration patterns, API quirks encountered
Update
```
template_patterns.md
```
with template designs, rendering approaches, reusable components

针对
skill="email-gateway"
遵循标准内存更新流程。存储任何新学到的模式、约定或项目洞察。

更新
```
provider_config.md
```
，添加服务商选择、配置模式、遇到的API特性
更新
```
template_patterns.md
```
，添加模板设计、渲染方式、可复用组件

Compliance Checklist

合规检查清单

Version History

版本历史

Version	Date	Changes
1.0.0	2025-07-18	Initial release — Resend, SendGrid, Mailgun, SMTP2Go support; unified API; template rendering; delivery tracking

版本	日期	变更内容
1.0.0	2025-07-18	初始版本 — 支持Resend、SendGrid、Mailgun、SMTP2Go；统一API；模板渲染；投递追踪