Skip to main content

Email plugin

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 config/plugins.js file or config/plugins.ts file. See the Providers documentation for detailed installation and configuration instructions.

✏️ Note

Sendmail 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 (refer to its README on npm) or change providers. The Providers documentation has instructions for changing providers, configuring providers, and creating a new email provider.

Sending emails with a controller or service

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

  • send() directly contains the email contents,
  • sendTemplatedEmail() 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 send() function to a controller or service. The send function has the following properties:

PropertyTypeFormatDescription
fromstringemail addressIf not specified, uses defaultFrom in plugins.js.
tostringemail addressRequired
ccstringemail addressOptional
bccstringemail addressOptional
replyTostringemail addressOptional
subjectstring-Required
textstring-Either text or html is required.
htmlstringHTMLEither text or html is required.
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 sendTemplatedEmail() function is used 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:

ParameterDescriptionTypeDefault
emailOptions
Optional
Contains email addressing properties: to, from, replyTo, cc, and bccobject{ }
emailTemplateContains email content properties: subject, text, and html using Lodash string templatesobject{ }
data
Optional
Contains the data used to compile the templatesobject{ }
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

To trigger an email based on administrator actions in the admin panel use lifecycle hooks and the send() function. For example, to send an email each time a new content entry is added in the Content Manager use the afterCreate lifecycle hook:

./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js

module.exports = {
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 plugin worked successfully',
text: '${fieldName}', // Replace with a valid field ID
html: 'Hello world!',

})
} catch(err) {
console.log(err);
}
}
}