# Email

Thanks to the plugin Email, you can send email from your server or externals providers such as Sendgrid.

# Programmatic usage

# Send an email - .send()

In your custom controllers or services you may want to send email. By using the following function, Strapi will use the configured provider to send an email.

Example

await strapi.plugins['email'].services.email.send({
  to: 'paulbocuse@strapi.io',
  from: 'joelrobuchon@strapi.io',
  cc: 'helenedarroze@strapi.io',
  bcc: 'ghislainearabian@strapi.io',
  replyTo: 'annesophiepic@strapi.io',
  subject: 'Use strapi email provider successfully',
  text: 'Hello world!',
  html: 'Hello world!',
});

# Send an email using a template - .sendTemplatedEmail()

When you send an email, you will most likely want to build it from a template you wrote. The email plugin provides the service sendTemplatedEmail that compile the email and then sends it. The function have the following params:

param description type default
emailOptions Object that contains email options (to, from, replyTo, cc, bcc) except subject, text and html object {}
emailTemplate Object that contains subject, text and html as lodash string templates (opens new window) object {}
data Object that contains the data used to compile the templates object {}

Example

const emailTemplate = {
  subject: 'Welcome <%= user.firstname %>',
  text: `Welcome on mywebsite.fr!
    Your account is now linked with: <%= user.email %>.`,
  html: `<h1>Welcome on 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, so it's the defaultFrom that will be used instead
  },
  emailTemplate,
  {
    user: _.pick(user, ['username', 'email', 'firstname', 'lastname']),
  }
);

# Configure the plugin

By default Strapi provides a local email system (sendmail (opens new window)). If you want to use a third party to send emails, you need to install the correct provider module. Otherwise you can skip this part and continue to configure your provider.

You can check all the available providers developed by the community on npmjs.org - Providers list (opens new window)

To install a new provider run:

# Using scoped packages as providers

If your package name is scoped (opens new window) (for example @username/strapi-provider-email-gmail-oauth2) you need to take an extra step by aliasing it in package.json. Go to the dependencies section and change the provider line to look like this:

"strapi-provider-email-gmail-oauth2": "npm:@username/strapi-provider-email-gmail-oauth2@0.1.9"

The string after the last @ represents your desired semver (opens new window) version range.

# 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.

💡 TIP

Make sure you have the correct spelling of the configuration filename, it is written in plural (with a trailing 's'): plugins.js.

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

Path — ./config/plugins.js.

module.exports = ({ env }) => ({
  // ...
  email: {
    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. More info here: Environments

💡 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. More info here: Configure templates Locally

# Create new provider

If you want to create your own, make sure the name starts with strapi-provider-email- (duplicating an existing one will be easier) and customize the send function.

Default template

module.exports = {
  init: (providerOptions = {}, settings = {}) => {
    return {
      send: async options => {},
    };
  },
};

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 as explained in the documentation eg. ./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"
        }
      ]
    }
  ]
}

This error is due to your IP connection. By default, Strapi uses the sendmail (opens new window) package.

This package sends an email from the server it runs on. Depending on the network you are on, the connection to the SMTP server could fail.

Here is the sendmail error.

Error: SMTP code:550 msg:550-5.7.1 [87.88.179.13] The IP you're using to send mail is not authorized to
550-5.7.1 send email directly to our servers. Please use the SMTP relay at your
550-5.7.1 service provider instead. Learn more at
550 5.7.1  https://support.google.com/mail/?p=NotAuthorizedError 30si2132728pjz.75 - gsmtp

To fix it, we suggest you to use another email provider that uses third party to send emails.

When using a third party provider, you avoid having to setup a mail server on your server and get extra features such as email analytics.

← GraphQL →