邮件营销
TanStack Ship 邮件营销系统，支持创建活动、通过 Cloudflare Queues 的队列投递和事务性邮件。
概述
TanStack Ship 的邮件营销系统支持创建、发送和追踪 HTML 邮件活动。由 Resend 提供可靠投递，Cloudflare Queues 提供异步处理，支持广播营销邮件和事务性通信。
作为 TanStack Ship 平台的一部分，邮件模块与账单系统（支付收据）、邀请系统（用户引导）和分析仪表板（活动效果追踪）集成。
设计流程
邮件营销系统编排从内容创建到队列投递再到投递追踪的完整活动交付管道：
核心能力
活动创建与管理
邮件活动管理界面（/dashboard/admin/email-campaigns）提供：
- 富文本 HTML 编辑器 — 使用可视化编辑器或原生 HTML 编写邮件
- 主题行与预览文本 — 可自定义的主题和预头
- 发件人配置 — 发件名称和邮箱地址
- 收件人选择 — 全部用户或分段群体
- 排期 — 立即发送或定时发送
基于队列的异步投递
邮件通过 Cloudflare Queues 异步发送，确保可靠性和性能：
- 活动在数据库中创建，状态为 DRAFT
- 管理员预览并发送活动
- 收件人作为单独消息入队
- 队列消费者处理每条消息，带重试逻辑
- 每次成功或失败发送后更新投递状态
这种架构防止 API 超时，确保即使初始请求失败也能完成投递。
事务性邮件
除营销活动外，系统还处理自动化事务性邮件：
- 支付确认和电子收据
- 账户验证和密码重置链接
- 邀请通知
- 账单提醒、订阅更新和支付失败通知
事务性邮件由服务端事件触发，通过同一个 Resend 集成发送。
客户端邮件活动列表示例：
import { useQuery } from '@tanstack/react-query'
export function CampaignList() {
const { data } = useQuery({
queryKey: ['email-campaigns'],
queryFn: () =>
fetch('/api/email-campaigns').then((r) => r.json()) as Promise<
Array<{
id: string
subject: string
status: string
sentCount: number
openRate: number
createdAt: string
}>
>,
})
return (
<div className="rounded-lg border divide-y">
{data?.map((c) => (
<div key={c.id} className="flex items-center justify-between p-4">
<div>
<p className="font-medium">{c.subject}</p>
<p className="text-xs text-muted-foreground">
{c.status} · {c.sentCount} 已发送 · 打开率 {c.openRate}%
</p>
</div>
</div>
))}
</div>
)
}
设计理念
默认异步投递
所有邮件活动通过 Cloudflare Queues 异步发送，绝不会在 HTTP 请求期间同步执行。当管理员点击"发送"时，活动收件人立即作为单独消息入队，API 立即返回。后台消费者处理每条消息，带有重试逻辑，每次发送完成时更新投递状态。这种架构防止了 HTTP 超时，确保即使 Resend API 暂时不可用也能完成投递，并允许系统处理大型活动（数千收件人）而不会阻塞服务器资源。与 Mailchimp 或 SendGrid 的同步发送模式不同——它们会阻塞 HTTP 响应直到投递完成，大型活动可能超时——我们的基于队列的架构将发送与请求生命周期解耦，实现任何规模下的可靠投递，无需服务端超时。
规模化可靠性
基于队列的投递系统对失败的投递实现指数退避重试，自动重试瞬时故障（速率限制、网络超时），同时最终标记持续失败的投递。这个可靠性层独立于管理界面运行——即使发送活动的管理员关闭了浏览器，活动也会处理完成。投递状态按收件人追踪，让管理员完全了解活动表现。
统一通信管道
事务性邮件（收据、通知、提醒）和营销活动共享同一个投递管道——相同的队列基础设施、相同的 Resend 集成、相同的投递追踪。这种统一的方法降低了运维复杂性：只有一个发送系统需要监控，一组投递指标需要追踪，一套配置（SPF、DKIM、DMARC）需要维护。事务性邮件绕过活动工作流，由服务端事件直接触发。
最佳实践
邮件可投递性设计
在 HTML 内容旁使用纯文本替代。保持 HTML 结构简单——避免过多图片和复杂布局，可能触发垃圾邮件过滤器。
发送前分段测试
在发送给全部用户之前，始终在小范围分段上测试活动。系统支持发送给选定的用户分段进行 A/B 测试。
监控退信率
定期审查活动分析的退信率和退订情况。高退信率表明需要处理列表卫生问题。
常见问题
系统使用哪个邮件提供商？ 系统使用 Resend 进行邮件投递。开发和生产环境都需要 Resend API 密钥。
能否向特定用户分段发送邮件？ 可以。活动创建界面支持选择全部用户或特定用户分段进行定向活动。
系统如何处理失败的邮件投递？ Cloudflare Queue 消费者对失败投递实现带指数退避的重试逻辑。耗尽重试次数后，投递在活动日志中标记为失败。
配置
邮件投递需要 Resend API 密钥和发件人配置，在 .dev.vars 中：
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=updates@yourdomain.com
RESEND_FROM_NAME=Your Product
生产环境中的异步邮件投递需要配置 Cloudflare Queue。队列消费者部署为 Cloudflare Worker。