电子邮件（Email）

页面摘要： 邮件功能通过本地 SMTP 或 SendGrid 等外部提供方发送事务性消息。本文档中的设置指南涵盖提供方配置，以及如何通过控制器或钩子扩展发送能力。

邮件（Email）功能使 Strapi 应用程序能够从服务器或外部提供方发送邮件。

• Plan：免费功能
• Role & permission：用户通过后端服务器发送邮件需具备 Email > "send" 权限
• Activation：默认可用
• Environment：在开发与生产环境中均可用

配置

邮件功能的大部分配置选项通过你的 Strapi 项目代码处理。管理面板提供当前配置的只读视图、连接状态、提供方能力，并允许用户发送测试邮件。

管理面板设置

配置该功能的路径： Settings > Email feature > Configuration

配置界面对于大多数字段是只读的。它显示当前的提供方配置，并允许用户测试连接。

配置面板中显示以下信息：

• Default sender email（默认发件人邮箱），以及如果配置的 defaultFrom 地址包含显示名称，则还有 Default sender name（默认发件人名称）。
• Default response email（默认回复邮箱），以及如果配置的 defaultReplyTo 地址包含显示名称，则还有 Default reply-to name（默认回复名称）。
• Email provider（邮件提供方）：当前使用的提供方。

当当前提供方暴露 SMTP 元数据时，主配置下方会出现一张 Provider capabilities（提供方能力） 卡片。它显示 SMTP 服务器地址、加密协议（TLS、STARTTLS 或 None）、身份验证类型和用户、池状态（启用连接池时为 Idle 或 Active），以及已启用功能（如 DKIM、OAuth2、速率限制和连接池）的标记。

此页面上唯一可由用户编辑的字段是 Test email delivery（测试邮件发送） 下的 Recipient email（收件人邮箱） 字段。一个 Send test email（发送测试邮件） 按钮会向该地址发送一封测试消息。

仅当当前角色启用了“Access the Email Settings page（访问邮件设置页面）”权限时，此页面才可见（更多信息请参阅 RBAC 功能 文档）：

基于代码的配置

邮件功能需要在 config/plugins.js|ts 文件中配置一个提供方及提供方配置。详细的安装和配置说明请参阅 提供方。

Sendmail 是 Strapi 邮件功能中默认的邮件提供方。它在内部使用 Nodemailer 进行邮件发送。它为本地开发环境提供了功能，但在默认配置下尚未达到生产就绪状态。对于生产阶段的应用程序，你需要进一步配置 Sendmail 或更改提供方。

邮件配置选项

插件配置在 config/plugins.js 文件或 config/plugins.ts 文件中定义。详细的、特定于提供方的安装和配置说明请参阅 提供方。

提供方（Providers）

邮件功能可以通过安装和配置额外的提供方来扩展。

提供方向插件的核心能力添加扩展，例如使用 Amazon SES 而非 Sendmail 来发送邮件。

既有由 Strapi 维护的官方提供方——可通过 应用市场 找到——也有许多由社区维护、可通过 npm 获取的提供方。

安装提供方

可以使用 npm 或 yarn 以 @strapi/provider-<plugin>-<provider> --save 格式安装新的提供方。

例如，安装 Sendgrid 提供方：

Yarn

yarn add @strapi/provider-email-sendgrid

NPM

npm install @strapi/provider-email-sendgrid --save

配置提供方

新安装的提供方在 the /config/plugins file 中启用和配置。如果该文件不存在，你必须创建它。

以下是 Sendgrid 提供方的配置示例：

JavaScript

module.exports = ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill')
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
        // region: 'eu', // Optional: set to 'eu' for EU data residency (default: 'global')
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

TypeScript

export default ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill')
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
        // region: 'eu', // Optional: set to 'eu' for EU data residency (default: 'global')
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

按环境配置

在配置你的提供方时，你可能希望根据 NODE_ENV 环境变量更改配置，或使用特定于环境的凭据。

你可以在 /config/env/{env}/plugins.js|ts 配置文件中设置特定的配置，它将用于覆盖默认配置。

某些提供方暴露类似于 SMTP 的连接细节，而不是（或除了）API 密钥。将这些值添加到 providerOptions 中，以便 Strapi 能够访问提供方主机。例如，社区 Nodemailer 提供方期望 host、port 和身份验证凭据：

JavaScript

module.exports = ({ env }) => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: env('SMTP_HOST'),
        port: env.int('SMTP_PORT', 587),
        secure: false, // Use `true` for port 465
        auth: {
          user: env('SMTP_USERNAME'),
          pass: env('SMTP_PASSWORD'),
        },
      },
      settings: {
        defaultFrom: 'no-reply@example.com',
        defaultReplyTo: 'support@example.com',
      },
    },
  },
});

TypeScript

export default ({ env }) => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: env('SMTP_HOST'),
        port: 587,
        secure: false, // Use `true` for port 465
        auth: {
          user: env('SMTP_USERNAME'),
          pass: env('SMTP_PASSWORD'),
        },
      },
      settings: {
        defaultFrom: 'no-reply@example.com',
        defaultReplyTo: 'support@example.com',
      },
    },
  },
});

如果你的提供方给你的是一个单独的 URL 而不是 host 和 port 值，请使用该包期望的键，在 providerOptions 中传入该 URL（例如 https://api.eu.mailgun.net）。

构建自定义提供方

要构建你自己的提供方、将其发布到 npm，或在你的项目中本地使用，请参阅专门文档：

• 创建自定义邮件提供方 — 实现提供方接口，然后将其发布到 npm 或在你的项目中本地使用。

使用

邮件功能使用 Strapi 全局 API，这意味着它可以从 Strapi 应用程序内部的任何位置调用，既可以通过 控制器或服务 从后端服务器本身调用，也可以从管理面板调用，例如在响应事件时（使用 生命周期钩子）。

使用控制器或服务发送邮件 {#controller-service}

邮件功能有一个 email 服务，其中包含 2 个用于发送邮件的函数：

• send() 直接包含邮件内容，
• sendTemplatedEmail() 使用来自内容管理器的数据填充邮件，简化程序化邮件的发送。

使用 send() 函数

要响应用户操作触发邮件，请将 send() 函数添加到 控制器 或 服务 中。send 函数具有以下属性：

以下代码示例可用于控制器或服务中：

await strapi.plugins['email'].services.email.send({
  to: 'valid email address',
  from: 'your verified email address', //e.g. single sender verification in SendGrid
  cc: 'valid email address',
  bcc: 'valid email address',
  replyTo: 'valid email address',
  subject: 'The Strapi Email feature worked successfully',
  text: 'Hello world!',
  html: 'Hello world!',
}),

使用 sendTemplatedEmail() 函数

sendTemplatedEmail() 函数用于从模板组合邮件。该函数从可用的属性编译邮件，然后发送邮件。

要使用 sendTemplatedEmail() 函数，请定义 emailTemplate 对象并将该函数添加到控制器或服务中。该函数调用 emailTemplate 对象，并可以可选调用 emailOptions 和 data 对象：

以下代码示例可用于控制器或服务中：

const emailTemplate = {
  subject: 'Welcome <%= user.firstname %>',
  text: `Welcome to mywebsite.fr!
    Your account is now linked with: <%= user.email %>.`,
  html: `<h1>Welcome to mywebsite.fr!</h1>
    <p>Your account is now linked with: <%= user.email %>.<p>`,
};

await strapi.plugins['email'].services.email.sendTemplatedEmail(
  {
    to: user.email,
    // from: is not specified, the defaultFrom is used.
  },
    emailTemplate,
  {
    user: _.pick(user, ['username', 'email', 'firstname', 'lastname']),
  }
);

从生命周期钩子发送邮件 {#lifecycle-hook}

要基于管理面板中的管理员操作触发邮件，请使用 生命周期钩子 和 send() 函数。

以下示例说明了如何在内容管理器中每次新增内容条目时，使用 afterCreate 生命周期钩子发送一封邮件：

JavaScript

module.exports = {
    async afterCreate(event) {    // Connected to "Save" button in admin panel
        const { result } = event;

        try{
            await strapi.plugin('email').service('email').send({ // you could also do: await strapi.service('plugin:email.email').send({
              to: 'valid email address',
              from: 'your verified email address', // e.g. single sender verification in SendGrid
              cc: 'valid email address',
              bcc: 'valid email address',
              replyTo: 'valid email address',
              subject: 'The Strapi Email feature worked successfully',
              text: '${fieldName}', // Replace with a valid field ID
              html: 'Hello world!', 
                
            })
        } catch(err) {
            console.log(err);
        }
    }
}

TypeScript

export default {
  async afterCreate(event) {    // Connected to "Save" button in admin panel
    const { result } = event;

    try{
      await strapi.plugins['email'].services.email.send({
        to: 'valid email address',
        from: 'your verified email address', // e.g. single sender verification in SendGrid
        cc: 'valid email address',
        bcc: 'valid email address',
        replyTo: 'valid email address',
        subject: 'The Strapi Email feature worked successfully',
        text: '${fieldName}', // Replace with a valid field ID
        html: 'Hello world!', 
      })
    } catch(err) {
      console.log(err);
    }
  }
}