> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 邮件订阅

> 一个 facade 后面两个 provider——默认 Resend Audiences，或者 Beehiiv（带双重确认 + broadcast 调度）。

邮件订阅是 SaaS 最便宜的增长渠道 —— 高意向用户主动举手要求后续触达,零广告成本。
但自己写一套订阅表单要 50 行代码:校验、反爬、audience 同步、"用户点订阅后看到什么"。

vibestrap 把整套流程接好:首页订阅卡片、Turnstile 防爬的 server action、audience
写入、订阅确认邮件,开箱即用。一行 config 在 **Resend**(默认 —— 同步到 Audience
让你后续 broadcast)和 **Beehiiv**(完整发布平台,带双重确认)之间切换。

## 前置条件

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

## 一步步配置（Resend）

1. 在 [resend.com/audiences](https://resend.com/audiences) 建一个 Audience，
   复制 ID——形如 `aud_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`。

2. 在 `.env.local` 加 env 变量：

   ```bash theme={null}
   RESEND_API_KEY=re_xxxxxxxxxxxx
   RESEND_AUDIENCE_ID=aud_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ```

3. 确认 `src/config/site.ts` 配置（默认就是 Resend）：

   ```ts theme={null}
   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：

   ```bash theme={null}
   BEEHIIV_API_KEY=bv_xxxxxxxxxxxx
   BEEHIIV_PUBLICATION_ID=pub_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ```

3. 在 `src/config/site.ts` 把 provider 切过去：

   ```ts theme={null}
   newsletter: {
     enable: true,
     provider: 'beehiiv',
   },
   ```

4. 在 Beehiiv 后台配双重确认（Settings → Subscribers → Confirmation）。
   Vibestrap 传的是 `reactivate_existing: true` 和 `send_welcome_email: false`，
   把确认邮件交给 Beehiiv 按你出版物的策略发。

## 怎么挑

| Provider | 适用场景                                                |
| -------- | --------------------------------------------------- |
| Resend   | 已经在用 Resend 发交易邮件，少一个供应商，且基础 Audience 够用。           |
| Beehiiv  | 真正的 newsletter 产品——落地页、付费订阅、推荐机制、broadcast 调度、数据看板。 |

## 验证生效

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](https://resend.com/docs/dashboard/audiences/introduction)
* Resend API：[resend.com/docs](https://resend.com/docs)
* Beehiiv API v2：[developers.beehiiv.com](https://developers.beehiiv.com/)
* Provider 源码：`src/newsletter/provider/{resend,beehiiv}.ts`