邮件订阅

vibestrap 自带 newsletter 模块，两家 provider：Resend（默认，同步到 Resend Audience） 和 Beehiiv（功能完整的发布平台，带双重确认和 broadcast 调度）。订阅表单在首页 footer， server action 校验邮箱后走当前激活的 provider。

​

前置条件

• Resend：Resend 账号、API key、在 dashboard 里建一个 Audience。
• Beehiiv：Beehiiv 出版物，从 Settings → Integrations → API 拿 API key。
• siteConfig.newsletter.enable 设为 true。

​

一步步配置（Resend）

1. 在 resend.com/audiences 建一个 Audience， 复制 ID——形如 aud_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
2. 在 .env.local 加 env 变量：
   RESEND_API_KEY=re_xxxxxxxxxxxx
   RESEND_AUDIENCE_ID=aud_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
3. 确认 src/config/site.ts 配置（默认就是 Resend）：
   newsletter: {
     enable: true,
     provider: 'resend',
   },
   
4. 重启 pnpm dev。在 footer 提交一次订阅，几秒内联系人就会出现在 Resend Audience 里。

​

一步步配置（Beehiiv）

1. 从 Beehiiv → Settings → Integrations 拿 publication ID， 形如 pub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
2. 在 .env.local 加 env：
   BEEHIIV_API_KEY=bv_xxxxxxxxxxxx
   BEEHIIV_PUBLICATION_ID=pub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
3. 在 src/config/site.ts 把 provider 切过去：
   newsletter: {
     enable: true,
     provider: 'beehiiv',
   },
   
4. 在 Beehiiv 后台配双重确认（Settings → Subscribers → Confirmation）。 vibestrap 传的是 reactivate_existing: true 和 send_welcome_email: false， 把确认邮件交给 Beehiiv 按你出版物的策略发。

​

怎么挑

​

验证生效

1. 用一个全新邮箱在 footer 提交一次订阅。
2. Resend：去 Resend dashboard 查 Audience——联系人应该在，unsubscribed: false。
3. Beehiiv：去 Subscribers → All——应该能看到那个邮箱，状态是 pending （还没点确认邮件）或 active（你关掉了确认）。
4. 用同一个邮箱再提一次。两家 provider 都会优雅处理（Resend 去重；Beehiiv reactivate）—— 不应该弹错误 toast。

​

常见坑

1. Resend：RESEND_AUDIENCE_ID 没配。任意 env 缺失，provider 会静默 no-op （dev 下日志会打 [newsletter/resend] Skipped）。表单提交看起来成功了， 但啥也没存。生产部署前两个 env 一定都要有。
2. Beehiiv：reactivate_existing 行为。如果联系人之前退订了，vibestrap 会在下次 订阅时自动激活。有些司法辖区要求重新订阅必须重新 opt-in——法务有意见就去 src/newsletter/provider/beehiiv.ts 改这个 flag。
3. GDPR（欧盟流量）。建议用 Beehiiv 并开启双重确认（默认就开），并在表单加同意 勾选框。Resend Audience 默认是单次确认；要做欧盟生意得自己接一遍确认邮件。
4. 同 key 不同环境。Resend 的 key 是按环境隔离的。同一个 RESEND_AUDIENCE_ID 不一定同时存在于 dev 和 prod 的 Resend 项目里——要么建两个 audience，要么共用同一个项目。
5. 切 provider。老 provider 里的订阅者留在原处，没有自动迁移——要从老的导出再导入新的。

​

在任意页面嵌表单

表单走 server action。爱挂哪挂哪——博客侧边栏、CTA 区域、弹窗都行。参考首页 footer 现有用法，组件抄过去就行，server action 会自动走当前激活 provider。

​

官方文档

• Resend Audiences：resend.com/docs/dashboard/audiences/introduction
• Resend API：resend.com/docs
• Beehiiv API v2：developers.beehiiv.com
• Provider 源码：src/newsletter/provider/{resend,beehiiv}.ts