 完整解析)
Wasp 邮件发送实战emailSender 声明、四种 Provider 配置与服务端 send() 完整解析【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本文基于 Wasp 框架 version-0.14 官方文档「Sending Emails」web/versioned_docs/version-0.14/advanced/email/email.md完整讲解如何在 Wasp 应用声明emailSender配置、选择 Dummy / SMTP / Mailgun / SendGrid 四种发送 provider 并配置对应环境变量以及如何通过wasp/server/email模块的emailSender.send()在 Action 中发出真实或模拟邮件。读完你能够独立搭建一套可开发、可上生产的全栈邮件发送链路并从源码层面理解 Wasp 是如何把「声明式配置」编译为服务端可执行代码的。一、整体思路声明一个 emailSender全局即可用Wasp 的邮件能力分为两层应用规范层main.wasp在应用声明中定义emailSender字段指定 provider 和可选的defaultFrom服务端运行时层src代码在 Action、Hook 等服务端代码中从wasp/server/email模块导入emailSender调用其send方法发送邮件。最小完整配置如下JavaScript / TypeScript 两种项目写法相同Wasp DSL 统一app Example { ... emailSender: { provider: provider, defaultFrom: { name: Example, email: helloitsme.com }, } }其中provider从以下四种中选择Dummy仅限开发SMTPMailgunSendGriddefaultFrom是可选字段。一旦定义后续每次发送邮件时就可以省略from字段不必反复填写发件人信息——这个「声明一次、全局生效」的设计正是声明式框架的价值所在。版本说明本文以 version-0.14 文档为准该版本使用 Wasp DSLmain.wasp中的app Example { ... }写法。当前仓库主干已迁移到 TypeScript Specmain.wasp.ts但邮件 SDK 的模板结构与 provider 实现保持一致源码佐证部分同样适用。二、快速上手用 emailSender.send() 发邮件在深入各家 provider 的接入细节之前先看一下发送邮件本身有多简单。你只需导入wasp/server/email模块导出的emailSender然后调用send方法import { emailSender } from wasp/server/email; // In some action handler... const info await emailSender.send({ from: { name: John Doe, email: johndoe.com, }, to: userdomain.com, subject: Saying hello, text: Hello world, html: Hello strongworld/strong, });TypeScript 项目完全同理仅文件后缀为sendEmail.ts。send方法返回一个描述邮件发送状态的对象具体结构随所用 provider 不同而变化下文第四节会给出源码级佐证。三、Provider 逐个接入不同 provider 需要的环境变量配置各不相同统一写在项目的.env.server文件中。四种 provider 的对照如下Provider适用场景需要的环境变量Dummy仅开发不真实发信无SMTP自建 SMTP 服务器或任何支持 SMTP 的交易邮件服务SMTP_HOST、SMTP_USERNAME、SMTP_PASSWORD、SMTP_PORTMailgunMailgun 交易邮件 APIMAILGUN_API_KEY、MAILGUN_DOMAINSendGridSendGrid 交易邮件 APISENDGRID_API_KEY3.1 Dummy Provider开发专用为了加快开发节奏Wasp 提供了一个Dummy邮件发送器它不会真实发送任何邮件而是把邮件内容console.log打印到控制台因此不需要任何配置。重要限制原文档配套说明 web/versioned_docs/version-0.14/advanced/email/_dummy-provider-note.mdDummyprovider 不用于生产环境只用于开发阶段。如果你尝试使用Dummyprovider 去 build 应用构建会直接失败——这是一道防止开发配置流入生产的硬性防线。设置方式app Example { ... emailSender: { provider: Dummy, } }从当前仓库的 SDK 模板源码可以看到它的实际行为dummy.tssend会以带颜色的边框格式打印From、To、Subject以及 Text/HTML 两部分正文然后统一返回{ success: true }。也就是说开发期你拿到的始终是一个“成功”结果方便无副作用地联调整条业务链路例如注册验证邮件的完整流程。3.2 SMTP Provider第一步在main.wasp中把 provider 设为SMTPapp Example { ... emailSender: { provider: SMTP, } }第二步在.env.server中补充以下环境变量SMTP_HOST SMTP_USERNAME SMTP_PASSWORD SMTP_PORT值得注意的是很多交易邮件服务商例如 Mailgun、SendGrid 以及其他不少服务本身也提供 SMTP 接入方式因此你完全可以不装对应的专用 SDK直接通过 SMTP provider 复用自己已有的交易邮件服务。从源码生成逻辑看index.tsWasp 在生成邮件 SDK 时会把env.SMTP_HOST、env.SMTP_PORT、env.SMTP_USERNAME、env.SMTP_PASSWORD组装成一个type: smtp的 provider 配置对象再交给initEmailSender初始化——四个环境变量的命名与上面完全一一对应。一个来自当前主干文档的实战提醒部分托管平台例如 Railway 免费套餐、Hetzner会封锁出站 SMTP 端口以防范垃圾邮件遇到发送失败时应优先考虑换用 Mailgun / SendGrid 这类专用集成而非纯 SMTP。3.3 Mailgun Provider在main.wasp中设置app Example { ... emailSender: { provider: Mailgun, } }然后获取 Mailgun 的 API Key 与 Domain写入.env.server。获取步骤访问 Mailgun 官网创建账户进入 API Keys 页面创建一个新 API Key复制 API Key添加到.env.server进入 Domains 页面创建一个新域名复制该域名添加到.env.server。MAILGUN_API_KEY MAILGUN_DOMAIN对照 SDK 模板源码可以看到 Mailgun provider 实际读取的正是env.MAILGUN_API_KEY、env.MAILGUN_DOMAIN以及可选的env.MAILGUN_API_URL后者用于切换 API 区域端点如 EU 区与文档声明一一对应。3.4 SendGrid Provider在main.wasp中设置app Example { ... emailSender: { provider: SendGrid, } }获取 SendGrid API Key访问 SendGrid 官网创建账户进入 API Keys 设置页创建新的 API Key复制 API Key添加到.env.server。SENDGRID_API_KEY现状提示来自当前主干文档SendGrid 已于 2025 年 5 月 27 日停止免费套餐现在需要付费计划才能发信如果你需要免费档位可以考虑改用 Mailgun 或 SMTP 方案。四、API Reference4.1emailSender配置字典app Example { ... emailSender: { provider: provider, defaultFrom: { name: Example, email: helloitsme.com }, } }字段说明provider: Provider必填 要使用的 provider取值Dummy、SMTP、Mailgun、SendGrid之一。 再次提醒Dummy仅限开发生产构建会失败。defaultFrom: dict可选 默认发件人信息。设置后发送邮件时即可省略from字段。4.2 JavaScript APIemailSender.send()import { emailSender } from wasp/server/email; // In some action handler... const info await emailSender.send({ from: { name: John Doe, email: johndoe.com, }, to: userdomain.com, subject: Saying hello, text: Hello world, html: Hello strongworld/strong, });send方法接收的参数对象字段字段类型必填说明fromobject否*发件人详情。若在main.wasp的emailSender中配置了defaultFrom此字段可省略from.namestring-发件人姓名from.emailstring-发件人邮箱地址tostring是收件人邮箱地址subjectstring是邮件主题textstring是邮件纯文本版本htmlstring是邮件 HTML 版本*from是否可省略取决于defaultFrom是否定义——这一点同样体现在代码生成器中见下节。五、源码纵深Wasp 如何把 emailSender 变成可运行的 SDK本节从当前仓库的 WASP CLIHaskell 编译器源码出发说明上述文档行为背后的生成机制帮助你在出问题时知道去哪里看。1. 生成入口与条件化输出。模块 EmailSenderG.hs 是邮件 SDK 的生成器genEmailSenderApi首先读取应用规范中的emailSender字段若未声明则不生成任何邮件代码返回空列表声明后才生成index.ts模板与core子目录。它通过EmailSenders.getEnabledEmailProvidersJson计算出启用的 provider作为模板数据注入。2. 只保留你选中的 provider。模板 core/index.ts 中每个 provider 的初始化函数导出都包在isSmtpProviderEnabled、isSendGridProviderEnabled、isMailgunProviderEnabled等条件块里——编译后你的项目里只会导出所选 provider 的initEmailSender其余被静态剔除。这与「Dummy 出现在生产构建中会失败」的约束是同一套机制的两面。3.defaultFrom的编译期内联。genCoreHelpers会把defaultFrom的email、name值以及「是否定义了 name」直接写进生成的core/helpers.tscore/types.ts还会得到isDefaultFromFieldDefined标志。这意味着send()里「from可省略」的行为是在编译期就定死的而不是运行时去查配置——这也是为什么修改defaultFrom需要重新编译 Wasp 项目。4. provider 配置全部来自环境变量。生成的 email/index.ts 按启用的 provider 组装配置对象SMTP 读SMTP_HOST/PORT/USERNAME/PASSWORDSendGrid 读SENDGRID_API_KEYMailgun 读MAILGUN_API_KEY/DOMAIN/API_URLDummy 无参数。最后统一导出为export const emailSender: EmailSender initEmailSender(emailProvider);即你在src中import { emailSender } from wasp/server/email拿到的对象。5. Dummy 的返回契约。如第三节所述Dummy 的send打印彩色邮件框后固定返回{ success: true }文档中「返回值随 provider 变化」正对应这里——各 provider 的init*EmailSender各自实现返回值语义。6. 依赖自动安装。depsRequiredByEmail函数会根据所选 provider 自动为项目添加相应的 npm 依赖各 provider 需要的 HTTP/邮件库你无需手动npm install发送库。补充说明超出 0.14 文档范围的当前主干能力供了解当前仓库的邮件 SDK 模板中已出现第 5 种 providerResend读取RESEND_API_KEY且最新文档采用main.wasp.ts的 TypeScript Spec 写法。若你从 0.14 升级邮件配置语法会随之变化建议对照当前主干文档 web/docs/advanced/email.md 迁移。六、小结与实践清单在main.wasp中声明emailSender时provider必填、defaultFrom可选开发期用Dummy零配置联调但要牢记带Dummy的构建会失败上线前必须切换。环境变量全部收敛在.env.serverSMTP 四件套SMTP_HOST/USERNAME/PASSWORD/PORT、Mailgun 双件套MAILGUN_API_KEY/DOMAIN、SendGrid 单密钥SENDGRID_API_KEY。业务代码只需import { emailSender } from wasp/server/email后调用send({ from?, to, subject, text, html })from在配置了defaultFrom时省略。遇到托管平台 SMTP 端口被封锁如 Railway 免费层、Hetzner时优先改用 Mailgun / SendGrid 专用集成。想深入或排查生成物问题直接看 EmailSenderG.hs 与 waspc/data/Generator/templates/sdk/wasp/server/email/ 下的模板配置项与环境变量的一一映射都清晰可见。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wasp 邮件发送实战：emailSender 声明、四种 Provider 配置与服务端 send() 完整解析
Wasp 邮件发送实战emailSender 声明、四种 Provider 配置与服务端 send() 完整解析【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本文基于 Wasp 框架 version-0.14 官方文档「Sending Emails」web/versioned_docs/version-0.14/advanced/email/email.md完整讲解如何在 Wasp 应用声明emailSender配置、选择 Dummy / SMTP / Mailgun / SendGrid 四种发送 provider 并配置对应环境变量以及如何通过wasp/server/email模块的emailSender.send()在 Action 中发出真实或模拟邮件。读完你能够独立搭建一套可开发、可上生产的全栈邮件发送链路并从源码层面理解 Wasp 是如何把「声明式配置」编译为服务端可执行代码的。一、整体思路声明一个 emailSender全局即可用Wasp 的邮件能力分为两层应用规范层main.wasp在应用声明中定义emailSender字段指定 provider 和可选的defaultFrom服务端运行时层src代码在 Action、Hook 等服务端代码中从wasp/server/email模块导入emailSender调用其send方法发送邮件。最小完整配置如下JavaScript / TypeScript 两种项目写法相同Wasp DSL 统一app Example { ... emailSender: { provider: provider, defaultFrom: { name: Example, email: helloitsme.com }, } }其中provider从以下四种中选择Dummy仅限开发SMTPMailgunSendGriddefaultFrom是可选字段。一旦定义后续每次发送邮件时就可以省略from字段不必反复填写发件人信息——这个「声明一次、全局生效」的设计正是声明式框架的价值所在。版本说明本文以 version-0.14 文档为准该版本使用 Wasp DSLmain.wasp中的app Example { ... }写法。当前仓库主干已迁移到 TypeScript Specmain.wasp.ts但邮件 SDK 的模板结构与 provider 实现保持一致源码佐证部分同样适用。二、快速上手用 emailSender.send() 发邮件在深入各家 provider 的接入细节之前先看一下发送邮件本身有多简单。你只需导入wasp/server/email模块导出的emailSender然后调用send方法import { emailSender } from wasp/server/email; // In some action handler... const info await emailSender.send({ from: { name: John Doe, email: johndoe.com, }, to: userdomain.com, subject: Saying hello, text: Hello world, html: Hello strongworld/strong, });TypeScript 项目完全同理仅文件后缀为sendEmail.ts。send方法返回一个描述邮件发送状态的对象具体结构随所用 provider 不同而变化下文第四节会给出源码级佐证。三、Provider 逐个接入不同 provider 需要的环境变量配置各不相同统一写在项目的.env.server文件中。四种 provider 的对照如下Provider适用场景需要的环境变量Dummy仅开发不真实发信无SMTP自建 SMTP 服务器或任何支持 SMTP 的交易邮件服务SMTP_HOST、SMTP_USERNAME、SMTP_PASSWORD、SMTP_PORTMailgunMailgun 交易邮件 APIMAILGUN_API_KEY、MAILGUN_DOMAINSendGridSendGrid 交易邮件 APISENDGRID_API_KEY3.1 Dummy Provider开发专用为了加快开发节奏Wasp 提供了一个Dummy邮件发送器它不会真实发送任何邮件而是把邮件内容console.log打印到控制台因此不需要任何配置。重要限制原文档配套说明 web/versioned_docs/version-0.14/advanced/email/_dummy-provider-note.mdDummyprovider 不用于生产环境只用于开发阶段。如果你尝试使用Dummyprovider 去 build 应用构建会直接失败——这是一道防止开发配置流入生产的硬性防线。设置方式app Example { ... emailSender: { provider: Dummy, } }从当前仓库的 SDK 模板源码可以看到它的实际行为dummy.tssend会以带颜色的边框格式打印From、To、Subject以及 Text/HTML 两部分正文然后统一返回{ success: true }。也就是说开发期你拿到的始终是一个“成功”结果方便无副作用地联调整条业务链路例如注册验证邮件的完整流程。3.2 SMTP Provider第一步在main.wasp中把 provider 设为SMTPapp Example { ... emailSender: { provider: SMTP, } }第二步在.env.server中补充以下环境变量SMTP_HOST SMTP_USERNAME SMTP_PASSWORD SMTP_PORT值得注意的是很多交易邮件服务商例如 Mailgun、SendGrid 以及其他不少服务本身也提供 SMTP 接入方式因此你完全可以不装对应的专用 SDK直接通过 SMTP provider 复用自己已有的交易邮件服务。从源码生成逻辑看index.tsWasp 在生成邮件 SDK 时会把env.SMTP_HOST、env.SMTP_PORT、env.SMTP_USERNAME、env.SMTP_PASSWORD组装成一个type: smtp的 provider 配置对象再交给initEmailSender初始化——四个环境变量的命名与上面完全一一对应。一个来自当前主干文档的实战提醒部分托管平台例如 Railway 免费套餐、Hetzner会封锁出站 SMTP 端口以防范垃圾邮件遇到发送失败时应优先考虑换用 Mailgun / SendGrid 这类专用集成而非纯 SMTP。3.3 Mailgun Provider在main.wasp中设置app Example { ... emailSender: { provider: Mailgun, } }然后获取 Mailgun 的 API Key 与 Domain写入.env.server。获取步骤访问 Mailgun 官网创建账户进入 API Keys 页面创建一个新 API Key复制 API Key添加到.env.server进入 Domains 页面创建一个新域名复制该域名添加到.env.server。MAILGUN_API_KEY MAILGUN_DOMAIN对照 SDK 模板源码可以看到 Mailgun provider 实际读取的正是env.MAILGUN_API_KEY、env.MAILGUN_DOMAIN以及可选的env.MAILGUN_API_URL后者用于切换 API 区域端点如 EU 区与文档声明一一对应。3.4 SendGrid Provider在main.wasp中设置app Example { ... emailSender: { provider: SendGrid, } }获取 SendGrid API Key访问 SendGrid 官网创建账户进入 API Keys 设置页创建新的 API Key复制 API Key添加到.env.server。SENDGRID_API_KEY现状提示来自当前主干文档SendGrid 已于 2025 年 5 月 27 日停止免费套餐现在需要付费计划才能发信如果你需要免费档位可以考虑改用 Mailgun 或 SMTP 方案。四、API Reference4.1emailSender配置字典app Example { ... emailSender: { provider: provider, defaultFrom: { name: Example, email: helloitsme.com }, } }字段说明provider: Provider必填 要使用的 provider取值Dummy、SMTP、Mailgun、SendGrid之一。 再次提醒Dummy仅限开发生产构建会失败。defaultFrom: dict可选 默认发件人信息。设置后发送邮件时即可省略from字段。4.2 JavaScript APIemailSender.send()import { emailSender } from wasp/server/email; // In some action handler... const info await emailSender.send({ from: { name: John Doe, email: johndoe.com, }, to: userdomain.com, subject: Saying hello, text: Hello world, html: Hello strongworld/strong, });send方法接收的参数对象字段字段类型必填说明fromobject否*发件人详情。若在main.wasp的emailSender中配置了defaultFrom此字段可省略from.namestring-发件人姓名from.emailstring-发件人邮箱地址tostring是收件人邮箱地址subjectstring是邮件主题textstring是邮件纯文本版本htmlstring是邮件 HTML 版本*from是否可省略取决于defaultFrom是否定义——这一点同样体现在代码生成器中见下节。五、源码纵深Wasp 如何把 emailSender 变成可运行的 SDK本节从当前仓库的 WASP CLIHaskell 编译器源码出发说明上述文档行为背后的生成机制帮助你在出问题时知道去哪里看。1. 生成入口与条件化输出。模块 EmailSenderG.hs 是邮件 SDK 的生成器genEmailSenderApi首先读取应用规范中的emailSender字段若未声明则不生成任何邮件代码返回空列表声明后才生成index.ts模板与core子目录。它通过EmailSenders.getEnabledEmailProvidersJson计算出启用的 provider作为模板数据注入。2. 只保留你选中的 provider。模板 core/index.ts 中每个 provider 的初始化函数导出都包在isSmtpProviderEnabled、isSendGridProviderEnabled、isMailgunProviderEnabled等条件块里——编译后你的项目里只会导出所选 provider 的initEmailSender其余被静态剔除。这与「Dummy 出现在生产构建中会失败」的约束是同一套机制的两面。3.defaultFrom的编译期内联。genCoreHelpers会把defaultFrom的email、name值以及「是否定义了 name」直接写进生成的core/helpers.tscore/types.ts还会得到isDefaultFromFieldDefined标志。这意味着send()里「from可省略」的行为是在编译期就定死的而不是运行时去查配置——这也是为什么修改defaultFrom需要重新编译 Wasp 项目。4. provider 配置全部来自环境变量。生成的 email/index.ts 按启用的 provider 组装配置对象SMTP 读SMTP_HOST/PORT/USERNAME/PASSWORDSendGrid 读SENDGRID_API_KEYMailgun 读MAILGUN_API_KEY/DOMAIN/API_URLDummy 无参数。最后统一导出为export const emailSender: EmailSender initEmailSender(emailProvider);即你在src中import { emailSender } from wasp/server/email拿到的对象。5. Dummy 的返回契约。如第三节所述Dummy 的send打印彩色邮件框后固定返回{ success: true }文档中「返回值随 provider 变化」正对应这里——各 provider 的init*EmailSender各自实现返回值语义。6. 依赖自动安装。depsRequiredByEmail函数会根据所选 provider 自动为项目添加相应的 npm 依赖各 provider 需要的 HTTP/邮件库你无需手动npm install发送库。补充说明超出 0.14 文档范围的当前主干能力供了解当前仓库的邮件 SDK 模板中已出现第 5 种 providerResend读取RESEND_API_KEY且最新文档采用main.wasp.ts的 TypeScript Spec 写法。若你从 0.14 升级邮件配置语法会随之变化建议对照当前主干文档 web/docs/advanced/email.md 迁移。六、小结与实践清单在main.wasp中声明emailSender时provider必填、defaultFrom可选开发期用Dummy零配置联调但要牢记带Dummy的构建会失败上线前必须切换。环境变量全部收敛在.env.serverSMTP 四件套SMTP_HOST/USERNAME/PASSWORD/PORT、Mailgun 双件套MAILGUN_API_KEY/DOMAIN、SendGrid 单密钥SENDGRID_API_KEY。业务代码只需import { emailSender } from wasp/server/email后调用send({ from?, to, subject, text, html })from在配置了defaultFrom时省略。遇到托管平台 SMTP 端口被封锁如 Railway 免费层、Hetzner时优先改用 Mailgun / SendGrid 专用集成。想深入或排查生成物问题直接看 EmailSenderG.hs 与 waspc/data/Generator/templates/sdk/wasp/server/email/ 下的模板配置项与环境变量的一一映射都清晰可见。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考