# Email

The Email plugin enables applications to send emails from a server or an external provider. The Email plugin uses the Strapi global API, meaning it can be called from anywhere inside a Strapi application. Two of the most common use cases are in the Strapi back end and in the admin panel. The following documentation describes how to use the Email plugin in a controller or service for back-end use cases and using a lifecycle hook for admin panel use cases.

PREREQUISITES

The Email plugin requires a provider and a provider configuration in the plugins.js file. See the Using providers documentation for detailed installation and configuration instructions.

✏️ NOTE

Sendmail (opens new window) is the default email provider in the Strapi Email plugin. 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. The Using providers documentation has instructions for changing providers, configuring providers, and creating a new email provider.

# Sending emails with a controller or service

The functions send and sendTemplatedEmail are available to send emails. The send function directly contains the email contents, while the sendTemplatedEmail function consumes data from the Content Manager to populate emails, streamlining programmatic emails.

# Using the send function

To trigger an email in response to a user action add the following function to a controller or service. There are several ways the send function can be used, but an example is wrapping a core action such as update. In this case, when a PUT request reaches the controller the record is updated and the send function sends the email.


// This code example can be used in a controller or a service
// path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.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 plugin worked successfully',
    text: 'Hello world!',
    html: 'Hello world!',
  }),

# Using the sendTemplatedEmail function

The Email plugin includes the function sendTemplatedEmail to compose emails from a template. The function compiles the email from the available properties and then sends the email. 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.

Parameter Description Type Default
emailOptions Contains email addressing properties: to, from, replyTo, cc, and bcc object { }
emailTemplate Contains email content properties: subject, text, and html using Lodash string templates (opens new window) object { }
data Contains the data used to compile the templates object { }

// This code example can be used in a controller or a service
// path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{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 with a lifecycle hook

Another use case for the Email plugin is to trigger an email based on administrator actions in the admin panel using Lifecycle hooks. For example, an editor can receive an email each time an author creates a new content entry in the Content Manager.

The following code example illustrates a lifecycle hook that runs when a new entry is created in the specified collection type. The following points are important for understanding the code example.

  • The afterCreate lifecycle event is initiated when an administrator clicks the Save button in the Content Manager.
  • The send function is identical to the back end example, with the same available properties.
  • Fields from the new content entry can be included in the email using the text property and replacing the value ${fieldName} with a valid field name.

// e.g. path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js

module.exports = {
    async afterCreate(event) {
        const { result } = event;

        try{
            await strapi.plugins['email'].services.email.send({
                to: 'a valid email address',
                from: 'a valid email address',
                subject: 'A new content entry',
                text: '${fieldName}'
            })
        } catch(err) {
            console.log(err);
        }
    }
}

← Upload →