Inbox Zero 事务性邮件包模板、Provider 抽象与 Resend 投递链路全解析【免费下载链接】inbox-zeroThe worlds best AI personal assistant for email. Open source app to help you reach inbox zero fast.项目地址: https://gitcode.com/GitHub_Trending/in/inbox-zeroinboxzero/transactional-email是 Inbox Zero 项目中负责所有事务性邮件Transactional Email的独立包它承载了每周邮件摘要、收件箱健康报告、邀请、发票、会议简报等全部邮件模板并通过统一的 Provider 接口接入实际投递服务当前实现为 Resend。本文将以该包的 README.md 为主线结合源码逐层拆解模板渲染、发送 API、投递抽象与本地开发预览的完整链路帮助你理解并复用这套「React 组件即邮件模板」的工程方案。包定位邮件模板与投递 API 的单一职责模块Inbox Zero 是一个开源的 AI 邮箱助手项目名见 README.md核心目标是帮助用户快速达到 Inbox Zero收件箱零未读。在整个仓库中事务性邮件被收敛到 packages/transactional-email 这个独立包内它只负责两件事用 React 组件基于react-email/react-email/components编写邮件模板通过统一的TransactionalEmailProvider接口将渲染后的 HTML 与纯文本投递出去。包清单定义在 package.json包名inboxzero/transactional-email入口为src/index.ts依赖react-email/components、react-email/render、react-email本地预览开发服务器、resend投递实现、nanoid生成邮件去重头部等脚本dev运行email dev --port 3010启动邮件预览服务test运行vitest run执行投递层单元测试引擎要求node 22.12.0。包入口 src/index.ts 只导出两条能力线send发送与contacts联系人管理分别对应 src/send.tsx 和 src/contacts.ts。本地运行与邮件实时预览README 给出了该包最直接的开发体验运行pnpm dev随后访问 http://localhost:3010/ 即可在浏览器中查看所有邮件模板的渲染预览。这背后是react-email提供的开发服务器email dev --port 3010。react-email会扫描emails/目录下的模板文件并为每个模板提供独立的预览页面同时支持交互式调试 props每个模板文件底部定义的TemplateName.PreviewProps就是预览数据源。例如 emails/summary.tsx 末尾的SummaryEmail.PreviewProps { baseUrl: https://www.getinboxzero.com, periodEnd: new Date(2024-03-20), archivedEmailCount: 8, // ... 其他示例数据 } satisfies SummaryEmailProps;这样的本地预览流程非常适合在调整模板布局、配色或内容结构时做即时视觉验证而无需真正发送一封邮件。Provider 抽象一套发送 API可插拔的投递实现README 明确指出邮件投递使用一个 provider 接口当前实现是 Resend。这一抽象体现在 src/provider.tsexport interface TransactionalEmailProvider { send( message: TransactionalEmailMessage, options?: TransactionalEmailSendOptions, ): PromiseTransactionalEmailProviderResult; }其中核心类型包括TransactionalEmailMessage统一的中立消息结构字段为from、to、subject、html、text以及可选的replyTo、headers、tags、attachmentsTransactionalEmailSendOptions发送选项含idempotencyKey幂等键与test测试模式TransactionalEmailProviderResult投递结果目前仅承载messageId。投递层的调度逻辑在 src/delivery.tsconst provider process.env.RESEND_API_KEY ? createResendTransactionalEmailProvider(process.env.RESEND_API_KEY) : null; export function isTransactionalEmailConfigured() { return provider ! null; } export async function deliverTransactionalEmail(message, options) { if (!provider) return null; return provider.send(message, options); }也就是说只要设置了RESEND_API_KEY环境变量投递链路就会被激活未配置时isTransactionalEmailConfigured()返回false发送调用会安全地打印提示日志并直接返回不会抛出异常。这一点在 src/delivery.test.ts 中有对应的单元测试覆盖未配置 key 时deliverTransactionalEmail解析为null配置 key 后则正确转发到 provider。Resend 实现细节当前唯一的 provider 实现在 src/providers/resend.ts。它做了两件值得注意的事测试模式重定向收件人当options.test为true时to会被替换为deliveredresend.devResend 官方测试收件地址避免测试邮件误发到真实用户幂等键透传idempotencyKey会原样传给 Resend SDK用于防止重复发送。provider 收到 Resend 的响应后若result.error存在则抛出Error sending email: message否则返回{ messageId: result.data?.id }。src/providers/resend.test.ts 验证了这两个行为消息字段到 Resend 请求的完整映射含附件、头部、tags、test 模式重定向以及 provider 错误的上抛。发送 API两条内部管线与十四类业务邮件所有业务发送函数都位于 src/send.tsx它们最终收敛到两个内部函数sendEmail面向「发给本站用户」的场景会附带List-Unsubscribe与List-Unsubscribe-Post退订头部后面详述参数包含unsubscribeToken与baseUrlsendTransactionalEmail面向不需要退订头部的场景支持附件与幂等键例如发票邮件。两条管线都先通过react-email/render的render(react)与render(react, { plainText: true })并行渲染出 HTML 与纯文本两个版本再组装消息调用deliverTransactionalEmail。渲染前的统一守卫是if (!isTransactionalEmailConfigured()) { console.log( Resend is not configured. You need to add a RESEND_API_KEY in your .env file for emails to work., ); return; }公共导出函数均以sendXxxEmail命名及其默认主题与分类标签tags供 Resend 数据分析使用汇总如下发送函数用途默认主题示例tag 值sendSummaryEmail每周邮件摘要Your weekly email summaryactivity-updatesendDigestEmail邮件规则摘要Digest由generateDigestSubject生成digestsendInboxHealthEmail收件箱健康建议We found N senders you rarely readinbox-healthsendInvitationEmail组织成员邀请Youre invited to join ... on Inbox ZeroinvitationsendReconnectionEmail提醒用户重新连接邮箱Reconnect your email account: ...reconnectionsendActionRequiredEmail需要用户处理的操作Action Required: ...action-requiredsendMeetingBriefingEmail会议前简报由generateMeetingBriefingSubject生成meeting-briefingsendMeetingRecapEmail会议后纪要由generateMeetingRecapSubject生成meeting-recapsendColdEmailNotification通知冷邮件发送者其邮件被拦截调用方传入cold-email-notificationsendGuestBookingConfirmationEmail访客预约确认Confirmed: ...booking-confirmationsendHostBookingConfirmationEmail宿主收到新预约New booking: ...booking-confirmationsendHostBookingCancellationEmail预约取消通知Booking canceled: ...booking-cancellationsendGuestBookingRescheduledEmail访客预约改期Rescheduled: ...booking-rescheduledsendHostBookingRescheduledEmail宿主预约改期Booking rescheduled: ...booking-rescheduledsendInvoiceEmail发票发送Your Inbox Zero invoiceinvoice其中sendColdEmailNotification是一个特例它的收件人是外部冷邮件发送者而非本站用户因此不携带退订 token而是通过In-Reply-To与References头部让通知邮件挂在原邮件线程下见 src/send.tsx 中的注释说明。sendInvoiceEmail则演示了附件能力——当传入attachmentUrl时会组装{ filename: invoice.pdf, path: attachmentUrl }附件并透传幂等键。所有发送函数的返回值统一为{ data, error }结构data.id即 provider 返回的messageId便于上层调用方做统一处理见toEmailSendResult。邮件头部与投递可送达性细节在sendEmail内部组装消息时有三处与可送达性直接相关的设计src/send.tsxheaders: { List-Unsubscribe: ${baseUrl}/api/unsubscribe?token${unsubscribeToken}, // From Feb 2024 Google requires this for bulk senders List-Unsubscribe-Post: List-UnsubscribeOne-Click, // Prevent threading on Gmail X-Entity-Ref-ID: nanoid(), }List-Unsubscribe指向应用内的退订接口/api/unsubscribe?token...token 由调用方传入通常是用户级或账户级的退订凭据List-Unsubscribe-Post注释明确说明「自 2024 年 2 月起 Google 要求批量发件人支持该头部」启用一键退订RFC 8058是提升 Gmail 投递率的关键头X-Entity-Ref-ID为每封邮件生成随机 ID防止 Gmail 把多封独立邮件错误地归入同一会话线程。这些头部保证了批量发送场景下退订合规与收件箱归类的正确性是该包「工程化」程度的重要体现。模板层React Email 组件与可复用布局所有模板位于 packages/transactional-email/emails共 15 个业务模板与 3 个共享组件业务模板action-required、cold-email-notification、digest、guest-booking-confirmation、guest-booking-rescheduled、host-booking-cancellation、host-booking-confirmation、host-booking-rescheduled、inbox-health、invitation、invoice、meeting-briefing、meeting-recap、reconnection、summary共享组件booking-email-layout预约类邮件统一布局、inbox-zero-footer品牌页脚、stats-email-footer统计邮件页脚含退订链接渲染。以 emails/summary.tsx 为例可以观察到模板的完整结构使用react-email/components的Html/Head/Preview/Body/Container/Section/Row/Column/Text/Link/Img/Tailwind等组件构建配合 Tailwind 类名与内联样式实现响应式布局Preview组件生成邮件客户端列表页的摘要文本SummaryEmailProps接口清晰定义了入参archivedEmailCount、needsReplyCount、coldEmailers、periodEnd、baseUrl、unsubscribeToken等并将数据进一步划分为「为你归档」「回复追踪Reply Zero」「冷邮件拦截」三个卡片区块与 Inbox Zero 的核心功能一一对应。页脚组件 inbox-zero-footer.tsx 则展示了「Sent via Inbox Zero」的品牌署名写法。联系人管理Audience 的增删除发送外包还通过 src/contacts.ts 暴露了 Resend 联系人Contact管理能力createContact({ email, audienceId? })创建联系人audience 优先取参数缺省时回退到环境变量RESEND_AUDIENCE_ID两者皆无则抛出Missing audienceIddeleteContact({ email, audienceId? })删除联系人规则同上。底层客户端单例在 src/client.ts同样以RESEND_API_KEY是否存在来决定是否初始化Resend实例。这意味着该包同时服务于「发信」与「维护订阅受众」两条业务线。在 Web 应用中的真实调用以 Digest 为例要理解这个包如何被上层使用可以看 apps/web/utils/digest/send-digest.ts。Digest 功能会同时投递到邮件、Slack、Teams、Telegram 等多个渠道其中邮件分支await sendDigestEmail({ from: env.RESEND_FROM_EMAIL, to: userEmail, emailProps: { baseUrl: env.NEXT_PUBLIC_BASE_URL, unsubscribeToken, date, ruleNames, ...itemsByRule, emailAccountId, }, });这里展示了该包的典型接入方式from取自环境变量RESEND_FROM_EMAILto是用户邮箱emailProps直接透传给DigestEmail模板组件同时通过 Prisma 查询的digestSendEmail开关控制是否走邮件渠道未配置任何可投递渠道时会抛出明确错误以避免 Digest 被错误标记为已发送。环境变量速查与适用前提综合源码使用该包需要配置的环境变量如下定义与读取位置见 src/delivery.ts、src/client.ts 与 apps/web/utils/digest/send-digest.ts环境变量作用缺失时行为RESEND_API_KEY激活投递链路并初始化 Resend provider发送函数打印提示日志后直接返回不抛错RESEND_FROM_EMAIL发件人地址上层应用传入from取决于上层调用RESEND_AUDIENCE_ID联系人管理时的默认 audience创建/删除联系人时抛出Missing audienceId需要说明的是本文描述以当前仓库代码为准投递实现依赖外部 Resend 服务因此真实发信能力需要有效的RESEND_API_KEY与已验证的发件域名未配置时仅本地预览pnpm dev与单元测试pnpm test可用。整个包的测试覆盖集中于投递调度与 provider 映射两层详见 src/delivery.test.ts 与 src/providers/resend.test.ts可作为新增 provider 实现时的参考模板。【免费下载链接】inbox-zeroThe worlds best AI personal assistant for email. Open source app to help you reach inbox zero fast.项目地址: https://gitcode.com/GitHub_Trending/in/inbox-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Inbox Zero 事务性邮件包：模板、Provider 抽象与 Resend 投递链路全解析
Inbox Zero 事务性邮件包模板、Provider 抽象与 Resend 投递链路全解析【免费下载链接】inbox-zeroThe worlds best AI personal assistant for email. Open source app to help you reach inbox zero fast.项目地址: https://gitcode.com/GitHub_Trending/in/inbox-zeroinboxzero/transactional-email是 Inbox Zero 项目中负责所有事务性邮件Transactional Email的独立包它承载了每周邮件摘要、收件箱健康报告、邀请、发票、会议简报等全部邮件模板并通过统一的 Provider 接口接入实际投递服务当前实现为 Resend。本文将以该包的 README.md 为主线结合源码逐层拆解模板渲染、发送 API、投递抽象与本地开发预览的完整链路帮助你理解并复用这套「React 组件即邮件模板」的工程方案。包定位邮件模板与投递 API 的单一职责模块Inbox Zero 是一个开源的 AI 邮箱助手项目名见 README.md核心目标是帮助用户快速达到 Inbox Zero收件箱零未读。在整个仓库中事务性邮件被收敛到 packages/transactional-email 这个独立包内它只负责两件事用 React 组件基于react-email/react-email/components编写邮件模板通过统一的TransactionalEmailProvider接口将渲染后的 HTML 与纯文本投递出去。包清单定义在 package.json包名inboxzero/transactional-email入口为src/index.ts依赖react-email/components、react-email/render、react-email本地预览开发服务器、resend投递实现、nanoid生成邮件去重头部等脚本dev运行email dev --port 3010启动邮件预览服务test运行vitest run执行投递层单元测试引擎要求node 22.12.0。包入口 src/index.ts 只导出两条能力线send发送与contacts联系人管理分别对应 src/send.tsx 和 src/contacts.ts。本地运行与邮件实时预览README 给出了该包最直接的开发体验运行pnpm dev随后访问 http://localhost:3010/ 即可在浏览器中查看所有邮件模板的渲染预览。这背后是react-email提供的开发服务器email dev --port 3010。react-email会扫描emails/目录下的模板文件并为每个模板提供独立的预览页面同时支持交互式调试 props每个模板文件底部定义的TemplateName.PreviewProps就是预览数据源。例如 emails/summary.tsx 末尾的SummaryEmail.PreviewProps { baseUrl: https://www.getinboxzero.com, periodEnd: new Date(2024-03-20), archivedEmailCount: 8, // ... 其他示例数据 } satisfies SummaryEmailProps;这样的本地预览流程非常适合在调整模板布局、配色或内容结构时做即时视觉验证而无需真正发送一封邮件。Provider 抽象一套发送 API可插拔的投递实现README 明确指出邮件投递使用一个 provider 接口当前实现是 Resend。这一抽象体现在 src/provider.tsexport interface TransactionalEmailProvider { send( message: TransactionalEmailMessage, options?: TransactionalEmailSendOptions, ): PromiseTransactionalEmailProviderResult; }其中核心类型包括TransactionalEmailMessage统一的中立消息结构字段为from、to、subject、html、text以及可选的replyTo、headers、tags、attachmentsTransactionalEmailSendOptions发送选项含idempotencyKey幂等键与test测试模式TransactionalEmailProviderResult投递结果目前仅承载messageId。投递层的调度逻辑在 src/delivery.tsconst provider process.env.RESEND_API_KEY ? createResendTransactionalEmailProvider(process.env.RESEND_API_KEY) : null; export function isTransactionalEmailConfigured() { return provider ! null; } export async function deliverTransactionalEmail(message, options) { if (!provider) return null; return provider.send(message, options); }也就是说只要设置了RESEND_API_KEY环境变量投递链路就会被激活未配置时isTransactionalEmailConfigured()返回false发送调用会安全地打印提示日志并直接返回不会抛出异常。这一点在 src/delivery.test.ts 中有对应的单元测试覆盖未配置 key 时deliverTransactionalEmail解析为null配置 key 后则正确转发到 provider。Resend 实现细节当前唯一的 provider 实现在 src/providers/resend.ts。它做了两件值得注意的事测试模式重定向收件人当options.test为true时to会被替换为deliveredresend.devResend 官方测试收件地址避免测试邮件误发到真实用户幂等键透传idempotencyKey会原样传给 Resend SDK用于防止重复发送。provider 收到 Resend 的响应后若result.error存在则抛出Error sending email: message否则返回{ messageId: result.data?.id }。src/providers/resend.test.ts 验证了这两个行为消息字段到 Resend 请求的完整映射含附件、头部、tags、test 模式重定向以及 provider 错误的上抛。发送 API两条内部管线与十四类业务邮件所有业务发送函数都位于 src/send.tsx它们最终收敛到两个内部函数sendEmail面向「发给本站用户」的场景会附带List-Unsubscribe与List-Unsubscribe-Post退订头部后面详述参数包含unsubscribeToken与baseUrlsendTransactionalEmail面向不需要退订头部的场景支持附件与幂等键例如发票邮件。两条管线都先通过react-email/render的render(react)与render(react, { plainText: true })并行渲染出 HTML 与纯文本两个版本再组装消息调用deliverTransactionalEmail。渲染前的统一守卫是if (!isTransactionalEmailConfigured()) { console.log( Resend is not configured. You need to add a RESEND_API_KEY in your .env file for emails to work., ); return; }公共导出函数均以sendXxxEmail命名及其默认主题与分类标签tags供 Resend 数据分析使用汇总如下发送函数用途默认主题示例tag 值sendSummaryEmail每周邮件摘要Your weekly email summaryactivity-updatesendDigestEmail邮件规则摘要Digest由generateDigestSubject生成digestsendInboxHealthEmail收件箱健康建议We found N senders you rarely readinbox-healthsendInvitationEmail组织成员邀请Youre invited to join ... on Inbox ZeroinvitationsendReconnectionEmail提醒用户重新连接邮箱Reconnect your email account: ...reconnectionsendActionRequiredEmail需要用户处理的操作Action Required: ...action-requiredsendMeetingBriefingEmail会议前简报由generateMeetingBriefingSubject生成meeting-briefingsendMeetingRecapEmail会议后纪要由generateMeetingRecapSubject生成meeting-recapsendColdEmailNotification通知冷邮件发送者其邮件被拦截调用方传入cold-email-notificationsendGuestBookingConfirmationEmail访客预约确认Confirmed: ...booking-confirmationsendHostBookingConfirmationEmail宿主收到新预约New booking: ...booking-confirmationsendHostBookingCancellationEmail预约取消通知Booking canceled: ...booking-cancellationsendGuestBookingRescheduledEmail访客预约改期Rescheduled: ...booking-rescheduledsendHostBookingRescheduledEmail宿主预约改期Booking rescheduled: ...booking-rescheduledsendInvoiceEmail发票发送Your Inbox Zero invoiceinvoice其中sendColdEmailNotification是一个特例它的收件人是外部冷邮件发送者而非本站用户因此不携带退订 token而是通过In-Reply-To与References头部让通知邮件挂在原邮件线程下见 src/send.tsx 中的注释说明。sendInvoiceEmail则演示了附件能力——当传入attachmentUrl时会组装{ filename: invoice.pdf, path: attachmentUrl }附件并透传幂等键。所有发送函数的返回值统一为{ data, error }结构data.id即 provider 返回的messageId便于上层调用方做统一处理见toEmailSendResult。邮件头部与投递可送达性细节在sendEmail内部组装消息时有三处与可送达性直接相关的设计src/send.tsxheaders: { List-Unsubscribe: ${baseUrl}/api/unsubscribe?token${unsubscribeToken}, // From Feb 2024 Google requires this for bulk senders List-Unsubscribe-Post: List-UnsubscribeOne-Click, // Prevent threading on Gmail X-Entity-Ref-ID: nanoid(), }List-Unsubscribe指向应用内的退订接口/api/unsubscribe?token...token 由调用方传入通常是用户级或账户级的退订凭据List-Unsubscribe-Post注释明确说明「自 2024 年 2 月起 Google 要求批量发件人支持该头部」启用一键退订RFC 8058是提升 Gmail 投递率的关键头X-Entity-Ref-ID为每封邮件生成随机 ID防止 Gmail 把多封独立邮件错误地归入同一会话线程。这些头部保证了批量发送场景下退订合规与收件箱归类的正确性是该包「工程化」程度的重要体现。模板层React Email 组件与可复用布局所有模板位于 packages/transactional-email/emails共 15 个业务模板与 3 个共享组件业务模板action-required、cold-email-notification、digest、guest-booking-confirmation、guest-booking-rescheduled、host-booking-cancellation、host-booking-confirmation、host-booking-rescheduled、inbox-health、invitation、invoice、meeting-briefing、meeting-recap、reconnection、summary共享组件booking-email-layout预约类邮件统一布局、inbox-zero-footer品牌页脚、stats-email-footer统计邮件页脚含退订链接渲染。以 emails/summary.tsx 为例可以观察到模板的完整结构使用react-email/components的Html/Head/Preview/Body/Container/Section/Row/Column/Text/Link/Img/Tailwind等组件构建配合 Tailwind 类名与内联样式实现响应式布局Preview组件生成邮件客户端列表页的摘要文本SummaryEmailProps接口清晰定义了入参archivedEmailCount、needsReplyCount、coldEmailers、periodEnd、baseUrl、unsubscribeToken等并将数据进一步划分为「为你归档」「回复追踪Reply Zero」「冷邮件拦截」三个卡片区块与 Inbox Zero 的核心功能一一对应。页脚组件 inbox-zero-footer.tsx 则展示了「Sent via Inbox Zero」的品牌署名写法。联系人管理Audience 的增删除发送外包还通过 src/contacts.ts 暴露了 Resend 联系人Contact管理能力createContact({ email, audienceId? })创建联系人audience 优先取参数缺省时回退到环境变量RESEND_AUDIENCE_ID两者皆无则抛出Missing audienceIddeleteContact({ email, audienceId? })删除联系人规则同上。底层客户端单例在 src/client.ts同样以RESEND_API_KEY是否存在来决定是否初始化Resend实例。这意味着该包同时服务于「发信」与「维护订阅受众」两条业务线。在 Web 应用中的真实调用以 Digest 为例要理解这个包如何被上层使用可以看 apps/web/utils/digest/send-digest.ts。Digest 功能会同时投递到邮件、Slack、Teams、Telegram 等多个渠道其中邮件分支await sendDigestEmail({ from: env.RESEND_FROM_EMAIL, to: userEmail, emailProps: { baseUrl: env.NEXT_PUBLIC_BASE_URL, unsubscribeToken, date, ruleNames, ...itemsByRule, emailAccountId, }, });这里展示了该包的典型接入方式from取自环境变量RESEND_FROM_EMAILto是用户邮箱emailProps直接透传给DigestEmail模板组件同时通过 Prisma 查询的digestSendEmail开关控制是否走邮件渠道未配置任何可投递渠道时会抛出明确错误以避免 Digest 被错误标记为已发送。环境变量速查与适用前提综合源码使用该包需要配置的环境变量如下定义与读取位置见 src/delivery.ts、src/client.ts 与 apps/web/utils/digest/send-digest.ts环境变量作用缺失时行为RESEND_API_KEY激活投递链路并初始化 Resend provider发送函数打印提示日志后直接返回不抛错RESEND_FROM_EMAIL发件人地址上层应用传入from取决于上层调用RESEND_AUDIENCE_ID联系人管理时的默认 audience创建/删除联系人时抛出Missing audienceId需要说明的是本文描述以当前仓库代码为准投递实现依赖外部 Resend 服务因此真实发信能力需要有效的RESEND_API_KEY与已验证的发件域名未配置时仅本地预览pnpm dev与单元测试pnpm test可用。整个包的测试覆盖集中于投递调度与 provider 映射两层详见 src/delivery.test.ts 与 src/providers/resend.test.ts可作为新增 provider 实现时的参考模板。【免费下载链接】inbox-zeroThe worlds best AI personal assistant for email. Open source app to help you reach inbox zero fast.项目地址: https://gitcode.com/GitHub_Trending/in/inbox-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考