React Email 邮件发送实战指南用 Resend、Nodemailer 与 SendGrid 交付你的 React 邮件模板【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu导读本指南面向已经用 React 组件搭建好 HTML 邮件模板如欢迎信、密码重置、通知、订单确认等事务性邮件的开发者。围绕仓库内.agents/skills/react-email技能文档中的发送规范SENDING.md完整讲解将 React Email 渲染产物投递给用户的四条主流路径——Resend MCP 工具、Resend Node.js SDK、模板托管Resend 模板上传以及 Nodemailer / SendGrid 等通用渠道并配合 Novu 仓库中真实使用 React Email 的源码佐证原理。读完你既能直接落地一套“渲染即发送”的代码也能理解每条路径背后的调用链与注意事项。为什么“发送”环节决定一封 React Email 的成败React Email 的核心价值是让你像写 React 组件一样编写 HTML 邮件而 SKILL.md 中的渲染部分揭示了它工作的一半通过render把 JSX 模板转成可直接投递的 HTML或通过{ plainText: true }生成纯文本版本。但模板被渲染出来之后仍需要交给邮件服务商Email Service ProviderESP才能真正进入收件人收件箱。本仓库对这一点有非常直观的印证novu/maily-render在 package.json 中把react-email/components与react-email/render列为运行时依赖其核心实现 maily.tsx 先把 JSON 内容映射成 React Email 的 JSX 标记再调用renderAsync完成 HTML/纯文本渲染——也就是说“渲染”只解决格式而“送达”依赖下方的发送通道。这正是本指南要补齐的另一半能力。发送前的硬性前提使用已验证域名Verified Domains这是 React Email 发送指南中唯一的一条“红线”规则无论选择哪条发送路径都必须遵守在from地址中使用已验证域名verified domains。如果用户未配置已验证域名请引导其先在邮件服务商处完成域名验证。原因在于现代邮件服务商普遍要求发件域名通过 SPF/DKIM 等身份校验否则投递会被判定为垃圾邮件甚至直接拒收。Resend、SendGrid 等 ESP 控制台都提供域名验证入口未验证前可用的沙箱发件地址如 Resend 的onboardingresend.dev只适合联调生产环境务必替换为已验证域名下的真实发件地址。路径一经 Resend 发送官方推荐当开发环境具备Resend MCP 工具时推荐流程是「先用render出 HTML 与纯文本再交给 MCP 的 send-email 工具投递」。完整示例来自 SENDING.mdimport { render } from react-email/components; import { WelcomeEmail } from ./emails/welcome; // Render to HTML const html await render( WelcomeEmail nameJohn verificationUrlhttps://example.com/verify / ); // Create plain text version const text await render(WelcomeEmail nameJohn verificationUrlhttps://example.com/verify /, { plainText: true });随后把以下字段交给 Resend MCP 的send-email工具即可torecipientexample.comsubjectWelcome to Acmehtml上一步渲染出的htmltext上一步渲染出的text双份渲染的价值示例中同时渲染 HTML 与 plain text并非冗余许多邮件客户端以及无障碍场景在默认不加载 HTML 时会读取纯文本版本而部分客户端对纯文本的匹配会直接决定“显示”还是“折叠”。仓库内novu/maily-render的 RenderOptions 同样把plainText作为一等渲染选项印证了文本版本是事务邮件投递的标配而非可选项。路径二无 MCP 时的 Resend Node.js SDK直传 React 组件若运行环境没有 Resend MCP 工具则使用官方 Node SDK。其独特优势在于react字段可以直接接收 React 组件由 SDK 内部自动完成 HTML 与纯文本的双重渲染无需手动先调renderimport { Resend } from resend; import { WelcomeEmail } from ./emails/welcome; const resend new Resend(process.env.RESEND_API_KEY); const { data, error } await resend.emails.send({ from: Acme onboardingresend.dev, to: [userexample.com], subject: Welcome to Acme, react: WelcomeEmail nameJohn verificationUrlhttps://example.com/verify / }); if (error) { console.error(Failed to send:, error); }要点拆解fromAcme ...格式右侧邮箱应位于已验证域名之下生产环境to字符串数组支持单个或多个收件人react接受 JSX 表达式SDK 内部替你完成 HTML 与纯文本渲染这是相比“手动 render 传 html/text”最省心的路径错误处理不可省略send返回{ data, error }结构务必显式检查error并做记录/告警这是 SKILL.md 中“Always check for errors when sending emails”的落地形态。从本仓库的实际模板也能看到 React 组件即模板的形态——usage-report 邮件 将Html、Head、Row、Column、Img、Link等组件按数据 props 组合成完整邮件结构验证了「组件 模板、props 渲染数据」这一 React Email 通用模式。路径三上传为 Resend 模板再发送Template 模式如果不希望每次都在代码里内联组件可以先把邮件模板上传到 Resend 侧托管之后通过模板 ID 引用发送。1. 初始化模板联动在终端执行npx react-emaillatest resend setup该命令会在终端提示你输入Resend API Key完成配置。这一步的本质是在本地 React Email 工作台与 Resend 之间建立授权关联。2. 上传模板配置完成后在 React Email 开发服务器界面的Resend 标签页中点击Upload上传单个邮件模板点击Bulk Upload一次性批量上传多个邮件。3. 用模板 ID 发送模板上传后获得唯一 ID后续通过 Resend SDK 的template字段引用即可await resend.emails.send({ from: Acme onboardingresend.dev, to: [userexample.com], subject: Welcome to Acme, template: { id: 1245-1256-1234-1234, } });模板模式的收益在于邮件视觉版本与发送逻辑解耦运营/设计人员可在服务商后台直接调整模板而不必发版应用代码。代价是你需要在两边维护模板状态适合需要频繁调整邮件外观而又不想走完整发版流程的团队。路径四通过 Nodemailer 与 SendGrid 等通用渠道发送React Email 对 ESP 并无绑定只要先把 JSX 渲染成 HTML就能对接任意支持 HTML 内容的邮件通道这也与 SENDING.md 中 “React Email supports sending with any email service provider” 的定位一致。NodemailerSMTP 通用通道适合企业自建 SMTP 或对接内部邮件网关import { render } from react-email/components; import nodemailer from nodemailer; const transporter nodemailer.createTransport({ host: smtp.example.com, port: 587, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } }); const html await render(WelcomeEmail nameJohn verificationUrlhttps://example.com/verify /); await transporter.sendMail({ from: noreplyexample.com, to: userexample.com, subject: Welcome, html });Nodemailer 只负责 SMTP 传输层因此 HTML 渲染需要自己完成from建议与 SMTP 账户域名一致便于通过发件身份校验。SendGridimport { render } from react-email/components; import sgMail from sendgrid/mail; sgMail.setApiKey(process.env.SENDGRID_API_KEY); const html await render(WelcomeEmail nameJohn verificationUrlhttps://example.com/verify /); await sgMail.send({ to: userexample.com, from: noreplyexample.com, subject: Welcome, html });三种渠道的取舍速查发送路径适用场景渲染方式模板管理Resend MCPAgent/AI 编程环境内快速交付先render出 html/text交给 MCP send-email无即发即走Resend Node SDK应用后端代码直发react字段自动渲染双版本无 / 可选 Template IDResend 模板上传需要运营在后台改版react-email resend setup UI 上传Resend 侧托管Nodemailer自有 SMTP/内网网关手动render自管理SendGrid已有 SendGrid 账户手动render自管理仓库侧源码佐证Novu 如何实际使用 React Email本指南内容并非孤立于仓库之外Novu 仓库内有大量与“渲染 发送”链条同源的落地代码可作参考渲染引擎依赖libs/maily-render/package.json 声明react-email/components^0.5.1与react-email/render^1.2.1依赖maily.tsx 直接 importBody、Button、Container、Heading、Html、Row、Section等 React Email 组件与发送文档示例中的组件体系完全一致。真实邮件模板usage-report 邮件 同时从react-email/components导入Body、Column、Container、Head、Html、Img、Link、Preview、Row、Section与render以完整Html结构组织说明生产级模板正是在这套组件体系上构建的。该文件将previewText通过Preview注入、所有图标资源使用 dashboard CDN 的绝对地址如 NOVU_LOGO_URL与“必须使用绝对图片 URL、始终提供 alt”等邮件最佳实践相互印证。渲染到 HTML 的输出形态Maily.render在关闭noHtmlWrappingTags时输出以HtmlHeadBodyContainer包裹的完整文档maily.tsx这正是可交给 Resend/Nodemailer/SendGrid 投递的 HTML 载荷可作为“渲染输出如何进入发送通道”的直接参考样例。读者若在自己的发送代码中需要更丰富的布局与主题能力可进一步阅读仓库内同一技能目录下的组件文档 COMPONENTS.md 与主流程说明 SKILL.md。发送前与发送后的质量红线综合发送文档与技能文档的规范正式投递前请逐条核对域名已验证from使用用户确认过的已验证域名无则先引导其到 ESP 完成验证发送前唯一硬约束双版本渲染Resend SDK 自动处理手写 Nodemailer/SendGrid 时务必同时维护 plain text绝对图片 URL图片托管在可靠 CDN保证alt文本避免布局跳动示例可参考仓库 usage-report 邮件 的图标引用方式错误处理所有发送调用都要检查返回值/异常失败路径必须有日志与可观测性不能静默吞掉生产体量约束Gmail 等客户端会裁剪过大邮件约 102KB 为常见阈值模板渲染后建议抽查体积邮件宽度以 600px 上下的移动端友好布局为准跨客户端测试发送代码稳定后至少在 Gmail、Outlook、Apple Mail 等主流客户端实测一轮渲染效果。以上任一环节踩坑投递都可能以“进入垃圾箱”或“渲染错乱”告终。把「组件渲染」与「渠道投递」看作同一流水线的两个阶段你的事务邮件系统才能在可控与可观测的前提下持续运行。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考