电子邮件

¥Email

电子邮件功能使 Strapi 应用能够从服务器或外部提供商发送电子邮件。

¥The Email feature enables Strapi applications to send emails from a server or an external provider.

功能的身份证

计划:免费功能。
角色和权限：电子邮件 > "send" 权限，供用户通过后端服务器发送电子邮件。
激活:默认可用。
环境:在开发和生产环境中均可用。

¥ Plan: Free feature.
Role & permission: Email > "send" permission for the user to send emails via the backend server.
Activation: Available by default.
Environment: Available in both Development & Production environment.

配置

¥Configuration

电子邮件功能的大多数配置选项都通过你的 Strapi 项目的代码处理。电子邮件功能无法在管理面板中配置，但是如果管理员已设置电子邮件，用户可以测试电子邮件传递。

¥Most configuration options for the Email feature are handled via your Strapi project's code. The Email feature is not configurable in the admin panel, however users can test email delivery if it has been setup by an administrator.

管理面板设置

¥Admin panel settings

配置功能的路径： 设置 > 电子邮件功能 > 配置

¥Path to configure the feature: Settings > Email feature > Configuration

在配置界面中，只有 "测试电子邮件传递" 下的电子邮件地址字段可供用户修改。发送测试电子邮件按钮可发送测试电子邮件。

¥In the Configuration interface, only the email address field under "Test email delivery" is modifiable by users. A Send test email button sends a test email.

此页面仅在当前角色启用了 "访问电子邮件设置页面" 权限时可见（有关更多信息，请参阅 RBAC 功能 文档）：

¥This page is only visible if the current role has the "Access the Email Settings page" permission enabled (see RBAC feature documentation for more information):

基于代码的配置

¥Code-based configuration

电子邮件功能需要提供商和 config/plugins.js 文件或 config/plugins.ts 文件中的提供商配置。有关详细的安装和配置说明，请参阅 提供者 文档。

¥The Email feature requires a provider and a provider configuration in the config/plugins.js file or config/plugins.ts file. See the Providers documentation for detailed installation and configuration instructions.

Providers

Learn more about configuring and creating providers for the Email and Media Library features.

发送邮件  是 Strapi 电子邮件功能中的默认电子邮件提供商。它为本地开发环境提供功能，但在默认配置中不适合生产。对于生产阶段应用，你需要进一步配置 Sendmail 或更改提供商。

¥Sendmail  is the default email provider in the Strapi Email feature. It provides functionality for the local development environment but is not production-ready in the default configuration. For production stage applications you need to further configure Sendmail or change providers.

电子邮件配置选项

¥Email Configuration Options

插件配置在 config/plugins.js 文件或 config/plugins.ts 文件中定义。有关提供商特定配置，请参阅 提供者 文档以获取详细的安装和配置说明。

¥Plugins configuration are defined in the config/plugins.js file or config/plugins.ts file. For provider specific configuration please see the Providers documentation for detailed installation and configuration instructions.

选项	类型	描述	默认值	注意
provider	string	要使用的电子邮件提供商。	sendmail	必需的
providerOptions	object	电子邮件提供商选项。	{}	可选的
providerOptions.apiKey	string	电子邮件提供商的 API 密钥。	''	可选的
settings	object	电子邮件设置。	{}	可选的
settings.defaultFrom	string	用作发件人的默认电子邮件地址。	''	可选的
settings.defaultReplyTo	string	用作回复地址的默认电子邮件地址。	''	可选的
ratelimit	object	电子邮件速率限制设置。	{}	可选的
ratelimit.enabled	boolean	是否启用速率限制。	true	可选的
ratelimit.interval	string	速率限制的间隔（分钟）。	5	可选的
ratelimit.max	number	间隔内允许的最大请求数。	5	可选的
ratelimit.delayAfter	number	应用速率限制之前允许的请求数。	1	可选的
ratelimit.timeWait	number	响应请求之前等待的时间（以毫秒为单位）。	1	可选的
ratelimit.prefixKey	string	速率限制键的前缀。	${userEmail}	可选的
ratelimit.whitelist	array(string)	要从速率限制中列入白名单的 IP 地址数组。	[]	可选的
ratelimit.store	object	速率限制存储位置，有关更多信息，请参阅 koa2-ratelimit 文档 。	MemoryStore	可选的

用法

¥Usage

电子邮件功能使用 Strapi 全局 API，这意味着它可以从 Strapi 应用中的任何位置调用，无论是通过 控制器或服务 从后端服务器本身调用，还是从管理面板调用，例如响应事件（使用 生命周期钩子）。

¥The Email feature uses the Strapi global API, meaning it can be called from anywhere inside a Strapi application, either from the back-end server itself through a controller or service, or from the admin panel, for example in response to an event (using lifecycle hooks).

使用控制器或服务发送电子邮件

¥Sending emails with a controller or service

电子邮件功能具有 email service，其中包含 2 个发送电子邮件的功能：

¥The Email feature has an email service that contains 2 functions to send emails:

• send() 直接包含电子邮件内容，

  ¥send() directly contains the email contents,

• sendTemplatedEmail() 使用内容管理器中的数据来填充电子邮件，从而简化程序化电子邮件。

  ¥sendTemplatedEmail() consumes data from the Content Manager to populate emails, streamlining programmatic emails.

使用 send() 功能

¥Using the send() function

要触发电子邮件以响应用户操作，请将 send() 函数添加到 controller 或 service。发送函数具有以下属性：

¥To trigger an email in response to a user action add the send() function to a controller or service. The send function has the following properties:

属性	类型	格式	描述
from	string	电子邮件地址	如果未指定，则在 plugins.js 中使用 defaultFrom。
to	string	电子邮件地址	必需的
cc	string	电子邮件地址	可选的
bcc	string	电子邮件地址	可选的
replyTo	string	电子邮件地址	可选的
subject	string	*	必需的
text	string	*	需要 text 或 html。
html	string	超文本标记语言	需要 text 或 html。

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

¥The following code example can be used in a controller or a service:

/src/api/my-api-name/controllers/my-api-name.ts|js (or /src/api/my-api-name/services/my-api-name.ts|js)

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() 功能

¥Using the sendTemplatedEmail() function

sendTemplatedEmail() 函数用于根据模板撰写电子邮件。该函数根据可用属性编译电子邮件，然后发送电子邮件。

¥The sendTemplatedEmail() function is used to compose emails from a template. The function compiles the email from the available properties and then sends the email.

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

¥To use the sendTemplatedEmail() function, define the emailTemplate object and add the function to a controller or service. The function calls the emailTemplate object, and can optionally call the emailOptions and data objects:

范围	描述	类型	默认
emailOptions 可选	包含电子邮件寻址属性：to、from、replyTo、cc 和 bcc	object
emailTemplate	包含电子邮件内容属性：subject、text 和 html 使用 Lodash 字符串模板	object
data 可选	包含用于编译模板的数据	object

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

¥The following code example can be used in a controller or a service:

/src/api/my-api-name/controllers/my-api-name.js (or ./src/api/my-api-name/services/my-api-name.js)

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']),
  }
);

从生命周期钩子发送电子邮件

¥Sending emails from a lifecycle hook

要根据管理面板中的管理员操作触发电子邮件，请使用 生命周期钩子 和 send() 功能。

¥To trigger an email based on administrator actions in the admin panel use lifecycle hooks and the send() function.

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

¥The following example illustrates how to send an email each time a new content entry is added in the Content Manager use the afterCreate lifecycle hook:

JavaScript

/src/api/my-api-name/content-types/my-content-type-name/lifecycles.js

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

/src/api/my-api-name/content-types/my-content-type-name/lifecycles.ts

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);
    }
  }
}