邮件订阅与候补名单
收集邮件订阅者和发布候补名单,同步到 Resend 或 Beehiiv,分批邀请用户并重试失败的同步。
邮件订阅模块提供公开的 /newsletter、/waitlist 和 /waitlist/status 页面,为每个新注册账号自动订阅,并把每次订阅、退订和邀请同步到 Resend 或 Beehiiv。不接入服务商时订阅同样可用。同步留在队列中,直到你接入服务商。
准备工作
- 一个能在本地运行的项目,见快速开始。
newsletter模块已经在底座仓库里,入口是后台侧边栏 内容 分组下的 Waitlist。 - 管理员账号:
newsletter.read用于打开页面;保存设置、批量邀请和重试同步还需要newsletter.write。 - 一个具备完整权限(Full access)的 Resend API Key 用于创建联系人,或者一个 Beehiiv API Key 及对应的 publication ID。
要给同事授权,在 概览 → 用户 中为其分配 Content Manager 角色。该角色包含两个订阅权限和 CMS 权限。
在订阅服务商准备账号
接入服务商
同一时间只启用一个服务商。
打开服务商设置
进入 内容 → Waitlist(/zh/admin/waitlist),打开 服务商设置 标签页(/zh/admin/waitlist/settings)。/setup 中的 订阅供应商 也链接到这里。
选择服务商并填写凭据
在 服务商 中选择 Resend 或 Beehiiv,然后填写对应字段:
按上方对应厂商指南中的字段对照表填写。
API Key 和 Publication ID 只写不读。已保存值的字段显示 已保存,留空则保留。
保存
点击 保存服务商设置。页面显示 订阅服务商设置已保存。,之后的订阅、退订和邀请会使用该服务商。
要停止同步,选择 未配置 并保存,之后的同步会留在队列中。
与邮件配置相互独立
模块本身不发送邮件,也不读取 邮件配置。保存在那里的 Resend Key 只用于事务邮件,订阅通讯需要在这里单独填写。
从候补名单发出邀请
打开批量邀请
打开 批量邀请 标签页(/zh/admin/waitlist/invites)。
邀请一批用户
填写 1 到 100 之间的 批次大小,点击 批量邀请。排队最久的等待记录会变为已邀请,并逐个同步到服务商。
通知用户
系统不会发送邀请邮件,请通过你自己的邮件流程发送。
重试排队中和失败的同步
服务商配置之前产生的同步仍在队列中,被服务商拒绝的同步记为失败。
打开批量邀请
打开 批量邀请 标签页(/zh/admin/waitlist/invites)。
重试
在 重试 provider 同步 区域填写 批次大小,点击 重试 provider 同步。最近一次尝试为 pending 或 failed 的同步会从最早的开始重试。
验证
- 打开
/zh/newsletter,用你能收信的邮箱订阅。 - 在 批量邀请 点击 重试 provider 同步。
- 日志表新增一行,服务商为你配置的服务商,状态为
success,Resend 或 Beehiiv 控制台中也会出现该联系人。
在仓库中,pnpm validate:newsletter 会运行这些流程。要验证真实服务商,设置 EXTERNAL_VALIDATE_NEWSLETTER_EMAIL 后运行 EXTERNAL_VALIDATE_STRICT=true pnpm validate:external。
常见问题
同步日志一直是 pending
没有配置服务商,因此没有发出请求。先接入服务商,再运行 重试 provider 同步。
同步日志显示 failed
服务商拒绝了请求,日志消息中包含其错误信息。在 服务商设置 中修正凭据后运行 重试 provider 同步。
保存服务商设置时报错
错误消息会指出原因:Resend needs an API key before it can be selected.、Beehiiv needs an API key and a publication id before it can be selected. 或 The Beehiiv API base URL must be an https URL.。表单填写完整之前不会保存任何内容。
候补用户没有收到邀请邮件
邀请只修改状态并同步联系人。请自行发送邮件。