email-sdk

Email SDK

当 Agent 使用此仓库，或将 @opencoredev/email-sdk 接入其他 TypeScript 应用时，使用此技能。

此技能会随项目动态变化：请勿将以下示例视为当前完整的 API 或模板目录。首先刷新本地软件包文档和源码，以确认已安装版本，然后根据仓库、依赖项以及当前机器可读文档实际提供的内容进行实现。

刷新当前文档

更改代码前，检查最相关的当前资料：

1. 如果你位于此仓库中，请阅读：
   • README.md
   • packages/email-sdk/README.md
   • packages/email-sdk/package.json
   • apps/fumadocs/content/docs/**/*.mdx
   • packages/email-sdk/src/index.ts
   • packages/email-sdk/src/<adapter>.ts 中具体的适配器文件
   • 当邮件形状、路由、重试、钩子或错误处理相关时，阅读 packages/email-sdk/src/types.ts、core.ts 和 errors.ts。
2. 如果你位于已安装 @opencoredev/email-sdk 的应用中，请检查：
   • 应用锁文件和 node_modules/@opencoredev/email-sdk/package.json
   • node_modules/@opencoredev/email-sdk/README.md
   • node_modules/@opencoredev/email-sdk/dist/*.d.ts
   • 应用现有的邮件、通知、队列、环境和测试模式。
3. 如果缺少本地文档，或任务依赖于版本敏感的行为，请在实现前获取当前已发布的软件包元数据和文档：
   • bun pm view @opencoredev/email-sdk
   • 如果目标应用中已安装 CLI，则运行 bun email-sdk version
   • 访问 https://email-sdk.dev/docs/llms.txt，发现当前文档目录
   • 访问 https://email-sdk.dev/docs/<path>.md，获取确切的原始 Markdown 页面
   • 获取正在使用的确切版本所对应的仓库文档或软件包 README。

优先使用原始 .md 端点，而不是抓取渲染后的 HTML。它们会返回 Content-Type: text/markdown，保留当前内部链接，并包含页面标题和规范路由。

对于 React Email UI 或模板相关工作：

1. 首先获取 https://email-sdk.dev/docs/ui.md。
2. 根据其中当前的分类和模板链接继续查阅，不要依赖硬编码的模板列表。
3. 以原始 Markdown 格式获取选定模板页面，例如 https://email-sdk.dev/docs/ui/account/verification-code.md。
4. 如果需要安装，请使用文档中的 shadcn@latest add 注册表 URL，或复制同一页面中的 Manual 源码。
5. 模板必须使用实际的 @opencoredev/email-sdk/react 基元；更改样式时，需验证邮件在浅色和深色主题下的效果。

如果本地源码与外部文档不一致，应以确切已安装版本的代码和类型为准，并说明两者不一致。

默认设置

• 优先使用 bun 和 bunx。
• 核心部分保持无依赖。
• 从单独的入口点导入适配器，例如 @opencoredev/email-sdk/resend、@opencoredev/email-sdk/smtp，以及当前软件包导出中列出的特定适配器入口点。
• 请勿为 SMTP 添加 Nodemailer；Email SDK 自带 SMTP 传输。
• 默认情况下，非安全端口上的 SMTP 身份验证会升级为 STARTTLS。仅对可信的本地测试服务器使用 allowInsecureAuth。
• 适配器必须映射标准化的 EmailMessage 字段，或明确拒绝该字段。绝不能静默丢弃 CC、BCC、reply-to、标头、标签、元数据或附件。
• 将适配器凭据保存在环境变量中。
• 绝不要记录 API 密钥、SMTP 密码、原始令牌、完整邮件正文或不必要的收件人数据。
• 保留宿主应用在队列、模板、环境验证、重试和测试方面的架构。

集成模式

像 @opencoredev/email-sdk/resend 和 @opencoredev/email-sdk/smtp 这样的入口点名称仅供参考。复制这些导入语句前，请先确认已安装版本导出的确切内容。

建议将 Email SDK 接入生产发送流水线：采用统一规范的消息结构、明确的适配器路由、对字段支持情况进行快速失败检查、重试、兼容的备用路由、安全保密的可观测性、测试和 CLI 验证。

import { createEmailClient } from "@opencoredev/email-sdk";
import { resend } from "@opencoredev/email-sdk/resend";
import { smtp } from "@opencoredev/email-sdk/smtp";

export const email = createEmailClient({
  adapters: [
    resend({ apiKey: process.env.RESEND_API_KEY! }),
    smtp({
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT ?? 587),
      auth: {
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!,
      },
    }),
  ],
  fallback: { adapters: ["smtp"] },
  retry: { maxAttempts: 2 },
});

备用路由和重试指南

• 选择备用路由前，请先查阅当前的字段支持文档或适配器源代码。
• 仅在备用适配器能够发送同类邮件，并保留应用所需的字段时才使用备用路由。
• 不要把 SMTP 当作通用备用方案；它最适合发送包含地址字段和标头的简单文本或 HTML 邮件。
• 对于可能重试或通过备用路由发送、且对外可见的事务性邮件，请使用幂等键。
• 使用钩子或 observabilityPlugin() 记录经过脱敏的路由、尝试、重试、成功和错误事件。
• 当备用路由或重试行为很重要时，请使用 memoryAdapter()、failingAdapter() 和 capturePlugin() 添加测试。
• 在检查实时服务提供商身份验证之前，请先使用 CLI 的 doctor 和 send --dry-run。
• 对于 v0 到 v1 的应用迁移，请使用独立的 email-sdk-migrate 技能，而不是应用静态查找替换规则。
• 对于从 2.x 升级到 v3，请遵循 /docs/guides/migrate/v2-to-v3：运行类型检查器，并修复非纯数据的发送选项 metadata。

在此仓库中，该模式的主要公开文档包括：

• apps/fumadocs/content/docs/guides/production-send-pipeline.mdx
• apps/fumadocs/content/docs/concepts/fallbacks-and-retries.mdx
• apps/fumadocs/content/docs/adapters/field-support.mdx

验证

• 对于 SDK 更改，请在 packages/email-sdk 中运行 bun test。
• 对于文档更改，在条件允许时，请从仓库根目录运行 bun run check-types 和 bun run build。
• 对于应用集成，请运行覆盖发送路径的最小范围测试或类型检查。
• 对于真实服务提供商的身份验证检查，请在可用时使用仓库中不会发送邮件的 live:* 脚本。未经用户另行批准，不要发送外部邮件。

审查清单

• 每次发送是否都包含 from、to、subject，以及 html 或 text 其中之一？
• 是否仅为能够发送同类邮件的适配器配置了备用路由？
• 对于对外可见的事务性邮件，是否使用了幂等键？
• 是否有暴露服务提供商错误，而不是将其吞掉？
• 钩子是否用于记录元数据和状态，而不是记录密钥或完整邮件正文？
• 当适配器负载的字段映射发生变化时，是否为其添加了测试？