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 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 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:

Property	Type	Format	Description
from	string	email address	If not specified, uses defaultFrom in plugins.js.
to	string	email address	Required
cc	string	email address	Optional
bcc	string	email address	Optional
replyTo	string	email address	Optional
subject	string	-	Required
text	string	-	Either text or html is required.
html	string	HTML	Either 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:

Parameter	Description	Type	Default
emailOptions Optional	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 Optional	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

To install a new provider run:

Configure your provider

After installing your provider you will need to add some settings in ./config/plugins.js. If this file doesn't exists, you'll need to create it. Check the README of each provider to know what configuration settings the provider needs.

✏️ NOTE

When using community providers, pass the full package name to the provider key (e.g. provider: 'strapi-provider-email-mandrill'). Only Strapi-maintained providers can use the shortcode format (e.g. provider: 'sendmail').

Here is an example of a configuration made for the provider @strapi/provider-email-sendgrid (opens new window).

Path — ``.

//path: ./config/plugins.js

module.exports = ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid',
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

//path: ./config/plugins.ts

export default = ({ env }) => ({
  // ...
  email: {
    config: {
      provider: 'sendgrid',
      providerOptions: {
        apiKey: env('SENDGRID_API_KEY'),
      },
      settings: {
        defaultFrom: 'juliasedefdjian@strapi.io',
        defaultReplyTo: 'juliasedefdjian@strapi.io',
        testAddress: 'juliasedefdjian@strapi.io',
      },
    },
  },
  // ...
});

💡 TIP

If you're using a different provider depending on your environment, you can specify the correct configuration in ./config/env/${yourEnvironment}/plugins.js (see environments configuration documentation).

💡 TIP

Only one email provider will be active at all time. If the email provider setting isn't picked up by strapi, verify you have put the file plugins.js in the correct folder, and with correct filename. The selection of email provider is done via configuration file only.

💡 TIP

When testing the new email provider with those two email templates created during strapi setup, the shipper email on the template, with default no-reply@strapi.io need to be updated in according to your email provider, otherwise it will fail the test (see Configure templates Locally).

Create new provider

Default template

In the send function you will have access to:

• providerOptions that contains configurations written in plugins.js
• settings that contains configurations written in plugins.js
• options that contains options you send when you call the send function from the email plugin service

To use it you will have to publish it on npm.

Create a local provider

If you want to create your own provider without publishing it on npm you can follow these steps:

• Create a providers folder in your application.
• Create your provider (e.g. ./providers/strapi-provider-email-[...]/...)
• Then update your package.json to link your strapi-provider-email-[...] dependency to the local path (opens new window) of your new provider.

{
  ...
  "dependencies": {
    ...
    "strapi-provider-email-[...]": "file:providers/strapi-provider-email-[...]",
    ...
  }
}

• Finally, run yarn install or npm install to install your new custom provider.

Troubleshooting

You received an Auth.form.error.email.invalid error even though the email is valid and exists in the database.

Here is the error response you get from the API.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    {
      "messages": [
        {
          "id": "Auth.form.error.email.invalid"
        }
    }
}