邮件订阅
配置 Resend、Beehiiv 或 MailCheap,管理邮件订阅和退订
MkSaaS 支持 Resend、Beehiiv 和 MailCheap 来管理邮件订阅。
设置
选择一个提供商,并配置对应的环境变量。模板默认使用 Resend;切换邮件订阅提供商不会改变事务性邮件的发送提供商。
创建 Resend 账户
在 resend.com 创建 Resend 账户。
获取 API 密钥
点击 API Keys > Create API Key,设置权限为 Send emails 或 Full access。复制 API Key,并添加到环境变量文件:
RESEND_API_KEY=YOUR-RESEND-API-KEY更新网站配置
export const websiteConfig = {
// ...其他配置
newsletter: {
enable: true,
provider: 'resend',
autoSubscribeAfterSignUp: false,
},
// ...其他配置
}如果您正在设置环境,现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。
环境配置
设置环境变量
使用方法
在服务端代码中调用以下函数:
import { subscribe, unsubscribe, isSubscribed } from '@/newsletter';
// 为用户订阅邮件列表
const subscriptionCreated = await subscribe('user@example.com');
// 为用户取消订阅邮件列表
const subscriptionRemoved = await unsubscribe('user@example.com');
// 检查用户是否已订阅邮件列表
const subscribed = await isSubscribed('user@example.com');邮箱地址在发送给提供商前会先去除首尾空格并转换为小写。同时启用 newsletter.enable 和 autoSubscribeAfterSignUp 后,用户会在完成邮箱验证,或通过已验证邮箱的 OAuth 账号注册后自动订阅。
Resend 提供商使用无需 Audience ID 的 Contacts API。它会先尝试创建联系人, 如果联系人已经存在则改为更新,因此重复订阅是安全的。
使用 MailCheap 时,只有联系人状态为 active,subscribe 和 isSubscribed 才会返回 true。如果 Newsletter 要求邮箱确认,新联系人可能处于 pending 状态;此时 MailCheap 可能已创建联系人,但当前订阅表单仍会报告失败。请先完成邮箱确认,并在 MailCheap 中核对联系人状态,再决定是否重试。
MailCheap 请求的每次尝试最多等待 20 秒,并使用原生 fetch 的默认行为跟随 HTTP 重定向。读取遇到网络或响应错误、HTTP 5xx 时会重试一次;写入不会自动重试,因为响应失败时写入也可能已经完成。
扩展新的邮件订阅服务
MkSaaS 支持扩展新的邮件订阅服务提供商:
- 在
src/newsletter/provider目录中创建新文件(例如custom-provider.ts)。 - 实现
NewsletterProvider接口:
import type {
CheckSubscribeStatusParams,
NewsletterProvider,
SubscribeNewsletterParams,
UnsubscribeNewsletterParams,
} from '@/newsletter/types';
export class CustomNewsletterProvider implements NewsletterProvider {
constructor() {
// 初始化您的邮件订阅服务提供商
}
public getProviderName(): string {
return 'CustomProvider';
}
async subscribe({ email }: SubscribeNewsletterParams): Promise<boolean> {
// 订阅用户的实现
return true;
}
async unsubscribe({ email }: UnsubscribeNewsletterParams): Promise<boolean> {
// 取消订阅用户的实现
return true;
}
async checkSubscribeStatus({ email }: CheckSubscribeStatusParams): Promise<boolean> {
// 检查订阅状态的实现
return true;
}
}- 在
src/types/index.d.ts的NewsletterConfig['provider']中加入提供商名称, 然后在index.ts注册延迟创建工厂:
import { CustomNewsletterProvider } from './provider/custom-provider';
const providerRegistry: Partial<
Record<NewsletterProviderName, NewsletterProviderFactory>
> = {
resend: () => new ResendNewsletterProvider(),
beehiiv: () => new BeehiivNewsletterProvider(),
mailcheap: () => new MailCheapNewsletterProvider(),
custom: () => new CustomNewsletterProvider(),
};常见问题
应该选择哪个提供商?
- 选择 Resend:如果您已经使用 Resend 发送事务性邮件,并希望有一个简单统一的解决方案来处理邮件发送和订阅管理。
- 选择 Beehiiv:如果您需要高级订阅功能,如数据分析、变现、推荐计划和增长工具,适合专业内容创作者。
- 选择 MailCheap:如果您希望通过模板统一的订阅、退订和状态查询接口管理 MailCheap Newsletter 的联系人。
环境变量RESEND_AUDIENCE_ID
从2025年11月15日起,RESEND_AUDIENCE_ID 环境变量已从模板中移除,邮件订阅功能已不再需要该环境变量。
具体详情参考文档:Migrating from Audiences to Segments
MkSaaS文档