邮件订阅与候补名单

收集邮件订阅者和发布候补名单,同步到 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 权限。

在订阅服务商准备账号

厂商适用场景
Resend使用联系人写入权限同步订阅者
Beehiiv将订阅者同步到指定 Publication

接入服务商

同一时间只启用一个服务商。

打开服务商设置

进入 内容 → 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 的同步会从最早的开始重试。

验证

  1. 打开 /zh/newsletter,用你能收信的邮箱订阅。
  2. 在 批量邀请 点击 重试 provider 同步。
  3. 日志表新增一行,服务商为你配置的服务商,状态为 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.。表单填写完整之前不会保存任何内容。

候补用户没有收到邀请邮件

邀请只修改状态并同步联系人。请自行发送邮件。

参考

下一步