LogoMkSaaS文档

邮件

学习如何使用 Resend 和 React Email 模板设置和使用邮件功能

MkSaaS 使用 Resend 进行邮件发送,使用 React Email 创建美观、响应式的邮件模板。这种组合为您的应用程序提供了现代化、开发者友好的邮件通信方式。

设置

  1. resend.com 创建 Resend 账户
  2. 在 Resend 控制台中点击 API Keys > Create API Key,设置权限为 Send emailsFull access,点击 Create API Key
  3. 获取 API 密钥,并添加到 .env 文件:
.env
RESEND_API_KEY=re_...
  1. 更新 website.tsx 文件以使用 Resend 作为邮件提供商,并设置默认发送者和接收者邮箱地址:
src/config/website.tsx
export const websiteConfig = {
  // ...其他配置
  mail: {
    provider: 'resend', // 要使用的邮件提供商
    contact: 'contact@example.com', // 默认发送者和接收者邮箱地址
  },
  // ...其他配置
}

如果您正在设置环境,现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置

设置环境变量


邮件系统架构

MkSaaS 中的邮件系统设计包含以下组件:

index.ts
types.ts
README.md

这种模块化结构使得扩展邮件系统的新提供商、模板和组件变得容易。

核心功能

  • 与 Resend 集成的事务性邮件发送
  • 使用 React Email 构建的美观、响应式邮件模板
  • 预构建的验证、密码重置和联系表单模板
  • 支持多语言邮件的国际化
  • 可重用的邮件组件(布局、按钮等)
  • 易于切换提供商的模块化架构
  • 用于邮件预览和测试的开发者工具

使用方法

MkSaaS 提供了一个简单的邮件发送工具,支持基于模板的邮件和原始内容:

import { sendEmail } from '@/mail';

// 使用模板发送
await sendEmail({
  to: 'user@example.com',
  template: 'verifyEmail',
  context: {
    name: 'John Doe',
    url: 'https://example.com/verify?token=abc123',
  },
  locale: 'en', // 可选,默认为配置的默认语言
});

// 发送原始邮件
await sendEmail({
  to: 'user@example.com',
  subject: '欢迎来到我们的平台',
  html: '<h1>您好!</h1><p>欢迎来到我们的平台。</p>',
  text: '您好!欢迎来到我们的平台。', // 可选
});

邮件模板

MkSaaS 包含几个预构建的邮件模板,适用于不同的使用场景:

邮件组件

MkSaaS 在 src/mail/components 目录中包含可重用的邮件组件,帮助构建一致的邮件模板:

预览邮件

MkSaaS 提供邮件预览功能,允许您在发送前预览邮件:

pnpm run email

这将启动一个本地服务器,允许您在浏览器中预览邮件。

预览邮件

自定义

创建自定义模板

  1. src/mail/templates 目录中创建 React 组件:
src/mail/templates/my-custom-email.tsx
import { BaseEmailProps } from '@/mail/types';
import { EmailLayout } from '../components/email-layout';
import { EmailButton } from '../components/email-button';

interface MyCustomEmailProps extends BaseEmailProps {
  username: string;
  actionUrl: string;
}

export function MyCustomEmail({
  username,
  actionUrl,
  messages,
  locale
}: MyCustomEmailProps) {
  return (
    <EmailLayout>
      <p>您好 {username}!</p>
      <p>感谢您加入我们的平台。点击下面的按钮开始使用。</p>
      <EmailButton href={actionUrl}>开始使用</EmailButton>
    </EmailLayout>
  );
}
  1. types.ts 中更新 EmailTemplates 接口以包含您的新模板:
src/mail/types.ts
export interface EmailTemplates {
  // ... 现有模板
  myCustomEmail: React.ComponentType<MyCustomEmailProps>;
}
  1. 如果需要,在您的 i18n 消息中添加相应的主题翻译

  2. 本地预览您的模板:

pnpm run email
npm run email
yarn email
bun run email
  1. 在您的代码中使用模板:
await sendEmail({
  to: 'user@example.com',
  template: 'myCustomEmail',
  context: {
    username: 'John',
    actionUrl: 'https://example.com/start',
  },
});

创建新的邮件提供商

MkSaaS 使得使用新提供商扩展邮件系统变得容易:

  1. src/mail/provider 目录中创建新文件
  2. types.ts 实现 MailProvider 接口
  3. index.ts 中更新提供商选择逻辑

新提供商的示例实现:

src/mail/provider/my-provider.ts
import { MailProvider, SendEmailResult, SendRawEmailParams, SendTemplateParams } from '@/mail/types';

export class MyProvider implements MailProvider {
  constructor() {
    // 初始化您的提供商
  }

  public async sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> {
    // 发送模板邮件的实现
  }

  public async sendRawEmail(params: SendRawEmailParams): Promise<SendEmailResult> {
    // 发送原始邮件的实现
  }

  public getProviderName(): string {
    return 'my-provider';
  }
}

然后在 index.ts 中更新提供商选择:

src/mail/index.ts
import { MyProvider } from './provider/my-provider';

export const initializeMailProvider = (): MailProvider => {
  if (!mailProvider) {
    if (websiteConfig.mail.provider === 'resend') {
      mailProvider = new ResendMailProvider();
    } else if (websiteConfig.mail.provider === 'custom') {
      mailProvider = new CustomMailProvider();
    } else {
      throw new Error(
        `不支持的邮件提供商: ${websiteConfig.mail.provider}`
      );
    }
  }

  return mailProvider;
};

最佳实践

  1. 验证邮箱地址:发送邮件前始终验证邮箱地址
  2. 优雅处理错误:当邮件发送失败时提供用户友好的错误消息

视频教程

下一步

现在您了解了如何在 MkSaaS 中使用邮件,您可能想要探索这些相关功能: