邮件 | TanStarter - Ship Faster with TanStack, Cost Less with Cloudflare

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

TanStarter 支持 Resend 和 Cloudflare Email Service 作为邮件提供商，使用 React Email 构建邮件模板。

设置

TanStarter 支持 Resend 和 Cloudflare Email Service 作为内置提供商。

Cloudflare Email

启用 Cloudflare Email Service

在 Cloudflare 控制台中启用邮件服务：

进入 Cloudflare 控制台 > Build > Compute > Email Service > Email Sending
点击右上角 Onboard Domain，添加并验证您发送邮件的域名（例如 example.com）

更多详情请参阅 Cloudflare Email Service 文档。

配置 Cloudflare API Token

请先完成 Cloudflare 配置，确保 Token 包含 Account > Email Sending > Edit 权限。

更新网站配置

更新 website.ts 文件以使用 Cloudflare 作为邮件提供商：

请注意 fromEmail 是发送邮件的邮箱地址，supportEmail 是接收邮件的邮箱地址（例如联系表单提交）。邮箱域名必须与您在 Cloudflare Email Service 中验证的域名一致。

src/config/website.ts

export const websiteConfig = {
  // ...其他配置
  mail: {
    enable: true,                                           // 是否启用邮件功能
    provider: 'cloudflare',                                 // 要使用的邮件提供商
    fromEmail: 'YourApp <support@example.com>',             // 发送邮件的邮箱地址
    supportEmail: 'YourApp <support@example.com>',          // 接收邮件的邮箱地址
  },
  // ...其他配置
}

Resend

创建 Resend 账户

在 resend.com 创建 Resend 账户，并绑定和验证您的网站域名

获取 API 密钥

进入 Resend 控制台 > API Keys，创建新的 API 密钥，设置权限时确保要包含发送邮件的权限

配置环境变量

将以下内容添加到您的 .env 文件中：

.env

RESEND_API_KEY=re_xxxxxxxxxxxx

更新网站配置

更新 website.ts 文件以使用 Resend 作为邮件提供商：

src/config/website.ts

export const websiteConfig = {
  // ...其他配置
  mail: {
    enable: true,                                           // 是否启用邮件功能
    provider: 'resend',                                     // 要使用的邮件提供商
    fromEmail: 'YourApp <support@example.com>',             // 发送邮件的邮箱地址
    supportEmail: 'YourApp <support@example.com>',          // 接收邮件的邮箱地址
  },
  // ...其他配置
}

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

环境配置

设置环境变量

自定义

创建新的邮件模板

在 src/mail/templates 目录中创建邮件模板：

src/mail/templates/my-custom-email.tsx

import { EmailLayout } from '../components/email-layout';
import { EmailButton } from '../components/email-button';

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

export function MyCustomEmail({
  username,
  actionUrl,
}: MyCustomEmailProps) {
  return (
    <EmailLayout>
      <p>您好 {username}！</p>
      <p>感谢您加入我们的平台。点击下面的按钮开始使用。</p>
      <EmailButton href={actionUrl}>开始使用</EmailButton>
    </EmailLayout>
  );
}

在 src/mail/types.ts 中添加模板名称到 EmailTemplate 类型：

src/mail/types.ts

export type EmailTemplate =
  | 'forgotPassword'
  | 'verifyEmail'
  | 'subscribeNewsletter'
  | 'contactMessage'
  | 'myCustomEmail'; // ← 添加您的模板名称

在 src/mail/render.ts 中注册组件：

src/mail/render.ts

import MyCustomEmail from './templates/my-custom-email';

const EmailTemplates = {
  forgotPassword: ForgotPassword,
  verifyEmail: VerifyEmail,
  subscribeNewsletter: SubscribeNewsletter,
  contactMessage: ContactMessage,
  myCustomEmail: MyCustomEmail, // ← 在此注册
} as const;

在消息文件（src/messages/en.ts）中添加邮件主题：

src/messages/en.ts

mail: {
  // ...已有模板
  myCustomEmail: {
    subject: 'Welcome to Our Platform',
  },
}

本地预览您的模板：

pnpm email:dev

在代码中使用模板：

await sendEmail({
  to: 'user@example.com',
  template: 'myCustomEmail',
  context: {
    username: 'John',
    actionUrl: 'https://example.com/start',
  },
});

创建新的邮件提供商

TanStarter 支持扩展新的邮件提供商：

在 src/mail/provider 目录中创建新文件（例如 sendgrid.ts）
实现 MailProvider 接口，该接口定义在 src/mail/types.ts 中，需要实现以下方法：

src/mail/provider/sendgrid.ts

import type {
  MailProvider,
  SendEmailResult,
  SendRawEmailParams,
  SendTemplateParams,
} from '../types';

export class SendGridProvider implements MailProvider {
  getProviderName(): string {
    return 'sendgrid';
  }

  async sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> {
    // 使用模板发送邮件的逻辑
  }

  async sendRawEmail(params: SendRawEmailParams): Promise<SendEmailResult> {
    // 发送原始 HTML 邮件的逻辑
  }
}

在 src/mail/index.ts 中的 providerRegistry 注册新的邮件提供商：

src/mail/index.ts

import { SendGridProvider } from './provider/sendgrid';

const providerRegistry: Record<MailProviderName, ProviderFactory> = {
  resend: () => new ResendProvider(),
  cloudflare: () => new CloudflareProvider(),
  sendgrid: () => new SendGridProvider(),
};

下一步

现在您了解了如何在 TanStarter 中使用邮件，您可能想要探索这些相关功能：

数据库

配置数据库

身份验证

配置身份验证

邮件订阅

配置邮件列表的订阅

环境配置

配置环境变量

TanStarter 支持 Resend 和 Cloudflare Email Service 作为邮件提供商，使用 React Email 构建邮件模板。

设置

TanStarter 支持 Resend 和 Cloudflare Email Service 作为内置提供商。

Cloudflare Email

启用 Cloudflare Email Service

在 Cloudflare 控制台中启用邮件服务：

进入 Cloudflare 控制台 > Build > Compute > Email Service > Email Sending
点击右上角 Onboard Domain，添加并验证您发送邮件的域名（例如 example.com）

更多详情请参阅 Cloudflare Email Service 文档。

配置 Cloudflare API Token

请先完成 Cloudflare 配置，确保 Token 包含 Account > Email Sending > Edit 权限。

更新网站配置

更新 website.ts 文件以使用 Cloudflare 作为邮件提供商：

src/config/website.ts

export const websiteConfig = {
  // ...其他配置
  mail: {
    enable: true,                                           // 是否启用邮件功能
    provider: 'cloudflare',                                 // 要使用的邮件提供商
    fromEmail: 'YourApp <support@example.com>',             // 发送邮件的邮箱地址
    supportEmail: 'YourApp <support@example.com>',          // 接收邮件的邮箱地址
  },
  // ...其他配置
}

Resend

创建 Resend 账户

在 resend.com 创建 Resend 账户，并绑定和验证您的网站域名

获取 API 密钥

进入 Resend 控制台 > API Keys，创建新的 API 密钥，设置权限时确保要包含发送邮件的权限

配置环境变量

将以下内容添加到您的 .env 文件中：

.env

RESEND_API_KEY=re_xxxxxxxxxxxx

更新网站配置

更新 website.ts 文件以使用 Resend 作为邮件提供商：

src/config/website.ts

export const websiteConfig = {
  // ...其他配置
  mail: {
    enable: true,                                           // 是否启用邮件功能
    provider: 'resend',                                     // 要使用的邮件提供商
    fromEmail: 'YourApp <support@example.com>',             // 发送邮件的邮箱地址
    supportEmail: 'YourApp <support@example.com>',          // 接收邮件的邮箱地址
  },
  // ...其他配置
}

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

环境配置

设置环境变量

自定义

创建新的邮件模板

在 src/mail/templates 目录中创建邮件模板：

src/mail/templates/my-custom-email.tsx

import { EmailLayout } from '../components/email-layout';
import { EmailButton } from '../components/email-button';

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

export function MyCustomEmail({
  username,
  actionUrl,
}: MyCustomEmailProps) {
  return (
    <EmailLayout>
      <p>您好 {username}！</p>
      <p>感谢您加入我们的平台。点击下面的按钮开始使用。</p>
      <EmailButton href={actionUrl}>开始使用</EmailButton>
    </EmailLayout>
  );
}

在 src/mail/types.ts 中添加模板名称到 EmailTemplate 类型：

src/mail/types.ts

export type EmailTemplate =
  | 'forgotPassword'
  | 'verifyEmail'
  | 'subscribeNewsletter'
  | 'contactMessage'
  | 'myCustomEmail'; // ← 添加您的模板名称

在 src/mail/render.ts 中注册组件：

src/mail/render.ts

import MyCustomEmail from './templates/my-custom-email';

const EmailTemplates = {
  forgotPassword: ForgotPassword,
  verifyEmail: VerifyEmail,
  subscribeNewsletter: SubscribeNewsletter,
  contactMessage: ContactMessage,
  myCustomEmail: MyCustomEmail, // ← 在此注册
} as const;

在消息文件（src/messages/en.ts）中添加邮件主题：

src/messages/en.ts

mail: {
  // ...已有模板
  myCustomEmail: {
    subject: 'Welcome to Our Platform',
  },
}

本地预览您的模板：

pnpm email:dev

在代码中使用模板：

await sendEmail({
  to: 'user@example.com',
  template: 'myCustomEmail',
  context: {
    username: 'John',
    actionUrl: 'https://example.com/start',
  },
});

创建新的邮件提供商

TanStarter 支持扩展新的邮件提供商：

在 src/mail/provider 目录中创建新文件（例如 sendgrid.ts）
实现 MailProvider 接口，该接口定义在 src/mail/types.ts 中，需要实现以下方法：

src/mail/provider/sendgrid.ts

import type {
  MailProvider,
  SendEmailResult,
  SendRawEmailParams,
  SendTemplateParams,
} from '../types';

export class SendGridProvider implements MailProvider {
  getProviderName(): string {
    return 'sendgrid';
  }

  async sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> {
    // 使用模板发送邮件的逻辑
  }

  async sendRawEmail(params: SendRawEmailParams): Promise<SendEmailResult> {
    // 发送原始 HTML 邮件的逻辑
  }
}

在 src/mail/index.ts 中的 providerRegistry 注册新的邮件提供商：

src/mail/index.ts

import { SendGridProvider } from './provider/sendgrid';

const providerRegistry: Record<MailProviderName, ProviderFactory> = {
  resend: () => new ResendProvider(),
  cloudflare: () => new CloudflareProvider(),
  sendgrid: () => new SendGridProvider(),
};