From 7d55b1a1fb080fa4cefa817ac28d4d4a6441a0f8 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 3 May 2022 15:41:21 +0200 Subject: [PATCH 01/74] fixed code snippets and added ts config --- docs/developer-docs/latest/plugins/email.md | 38 +++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 9885fe6347..691523fcd7 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -Thanks to the plugin `Email`, you can send email from your server or externals providers such as **Sendgrid**. +The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. ## Programmatic usage @@ -33,7 +33,7 @@ await strapi.plugins['email'].services.email.send({ ### 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: +The email plugin provides the service `sendTemplatedEmail` that compiles the email and then sends it. The function has the following parameters: | param | description | type | default | | --------------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | @@ -106,9 +106,12 @@ When using community providers, pass the full package name to the `provider` key Here is an example of a configuration made for the provider [@strapi/provider-email-sendgrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid). -**Path —** `./config/plugins.js`. + + ```js +//path: ./config/plugins.js + module.exports = ({ env }) => ({ // ... email: { @@ -128,6 +131,35 @@ module.exports = ({ env }) => ({ }); ``` + + + +```js +//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`. More info here: [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) ::: From cf6423f1932e33971c54f28cc24b11da221aa770 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 4 May 2022 20:51:50 +0200 Subject: [PATCH 02/74] added new introduction --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 691523fcd7..18aefc472c 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. +The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to affectuate programicatic email. ## Programmatic usage From e9f7a09cf16b67f326709498ca7a9272d6968108 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Fri, 6 May 2022 10:12:36 +0200 Subject: [PATCH 03/74] revised wording --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 18aefc472c..86d22fc616 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -68,7 +68,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( By default Strapi provides a local email system ([sendmail](https://www.npmjs.com/package/sendmail)). 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. -Below are the providers maintained by the Strapi team: +The Strapi team maintains the following providers: - [Amazon SES](https://www.npmjs.com/package/@strapi/provider-email-amazon-ses) - [Mailgun](https://www.npmjs.com/package/@strapi/provider-email-mailgun) From 2da98dccd0c1fb3850b27099f6c98ce63a7797db Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 1 Jun 2022 16:42:30 +0200 Subject: [PATCH 04/74] add tabs card --- docs/developer-docs/latest/plugins/email.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 86d22fc616..eff5f530ac 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -106,6 +106,8 @@ When using community providers, pass the full package name to the `provider` key Here is an example of a configuration made for the provider [@strapi/provider-email-sendgrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid). +:::: tabs card +::: tab SENDGRID @@ -160,6 +162,9 @@ export default ({ env }) => ({ +::: +:::: + ::: 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](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) ::: From 5665e0905b38e0263f79df1857f17daec7e40684 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 2 Jun 2022 13:57:49 +0200 Subject: [PATCH 05/74] Add code snippets for providers --- docs/developer-docs/latest/plugins/email.md | 241 ++++++++++++++++++++ 1 file changed, 241 insertions(+) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index eff5f530ac..6b9179b236 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -107,6 +107,7 @@ When using community providers, pass the full package name to the `provider` key Here is an example of a configuration made for the provider [@strapi/provider-email-sendgrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid). :::: tabs card + ::: tab SENDGRID @@ -163,6 +164,246 @@ export default ({ env }) => ({ ::: + +::: tab AMAZON-SES + + + +```js +//path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'amazon-ses', + providerOptions: { + key: env('AWS_SES_KEY'), + secret: env('AWS_SES_SECRET'), + amazon: 'https://email.us-east-1.amazonaws.com', + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` + + + + +```js +//path: ./config/plugins.ts + +export default ({ env }) => ({ + // ... + email: { + config: { + provider: 'amazon-ses', + providerOptions: { + key: env('AWS_SES_KEY'), + secret: env('AWS_SES_SECRET'), + amazon: 'https://email.us-east-1.amazonaws.com', + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); + +``` + + + + +::: + +::: tab MAILGUN + + + +```js +//path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'mailgun', + providerOptions: { + apiKey: env('MAILGUN_API_KEY'), + domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains + host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` + + + + +```js +//path: ./config/plugins.ts + +export default ({ env }) => ({ + // ... + email: { + config: { + provider: 'mailgun', + providerOptions: { + apiKey: env('MAILGUN_API_KEY'), + domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains + host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); + +``` + + + + +::: + +::: tab NODEMAILER + + + +```js +//path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'nodemailer', + providerOptions: { + host: env('SMTP_HOST', 'smtp.example.com'), + port: env('SMTP_PORT', 587), + auth: { + user: env('SMTP_USERNAME'), + pass: env('SMTP_PASSWORD'), + }, + // ... any custom nodemailer options + }, + settings: { + defaultFrom: 'hello@example.com', + defaultReplyTo: 'hello@example.com', + }, + }, + }, + // ... +}); + +``` + + + + +```js +//path: ./config/plugins.ts + +export default ({ env }) => ({ + // ... + email: { + config: { + provider: 'nodemailer', + providerOptions: { + host: env('SMTP_HOST', 'smtp.example.com'), + port: env('SMTP_PORT', 587), + auth: { + user: env('SMTP_USERNAME'), + pass: env('SMTP_PASSWORD'), + }, + // ... any custom nodemailer options + }, + settings: { + defaultFrom: 'hello@example.com', + defaultReplyTo: 'hello@example.com', + }, + }, + }, + // ... +}); + + +``` + + + + +::: + +::: tab SENDMAIL + + + +```js +//path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendmail', + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); + + +``` + + + + +```js +//path: ./config/plugins.ts + +export default ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendmail', + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); + + +``` + + + + +::: + :::: ::: tip From b036b887d8a63d8c6b1ea185a56a0b164fcd05ed Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 2 Jun 2022 13:59:01 +0200 Subject: [PATCH 06/74] Reorg doc structure --- docs/developer-docs/latest/plugins/email.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 6b9179b236..74611af0b4 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,14 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to affectuate programicatic email. +The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. + +## Setup an email provider + +By default Strapi provides a local email system ([sendmail](https://www.npmjs.com/package/sendmail)). 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. + + + ## Programmatic usage From 18a3f35350ee660417220d4fb00386151d407cec Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 20 Jun 2022 13:29:16 +0200 Subject: [PATCH 07/74] adds Using Providers page --- docs/.vuepress/config/sidebar-developer.js | 1 + .../latest/development/using-providers.md | 196 ++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 docs/developer-docs/latest/development/using-providers.md diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 9a8dbf3b8b..e728198717 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -222,6 +222,7 @@ const developer = [ ['/developer-docs/latest/development/admin-customization', 'Admin panel customization'], ['/developer-docs/latest/development/plugins-extension.md', 'Plugins extension'], ['/developer-docs/latest/development/plugins-development.md', 'Plugins development'], + ['/developer-docs/latest/development/using-providers.md', 'Using providers'], ], }, { diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md new file mode 100644 index 0000000000..1dadc77872 --- /dev/null +++ b/docs/developer-docs/latest/development/using-providers.md @@ -0,0 +1,196 @@ +--- +title: Using Providers - Strapi Developer Docs +description: Install and use providers to extend the functionality of available plugins. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/using-providers.html +--- + +# Using Providers + +Certain [plugins](../../../user-docs/latest/plugins/introduction-to-plugins.md) can be extended via the installation and configuration of additional [providers](../../../user-docs/latest/plugins/introduction-to-plugins.md#providers). + +Providers add an extension to the core capabilities of the plugin, for example to upload media files to Rackspace instead of the local server, or using Amazon SES for emails instead of Sendmail. + +::: note +Only the [Upload](./upload.md) and [Email](./email.md) plugins are currently designed to work with providers. +::: + +For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [NPM](https://www.npmjs.com/). + +## Installing providers + +Install new providers using `npm` or `yarn` using the format `@strapi/provider-- --save`. + +For example: + + + + +```sh +# Install the AWS S3 provider for the Upload plugin +npm install @strapi/provider-upload-aws-s3 --save + +# Install the Sendgrid provider for the Email plugin +npm install @strapi/provider-email-sendgrid --save +``` + + + +```sh +# Install the AWS S3 provider for the Upload plugin +yarn add @strapi/provider-upload-aws-s3 + +# Install the Sendgrid provider for the Email plugin +yarn add @strapi/provider-email-sendgrid --save +``` + + + + +## Configuring providers + +Newly installed providers are enabled and configured in the `./config/plugins.js` file. If this file does not exist you must create it. + +Each provider will have different configuration settings available, review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [NPM](https://www.npmjs.com/) to learn more. + +Below are example configurations for the Upload and Email plugins. + +::: tab Upload + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + upload: { + config: { + provider: 'aws-s3', // For community providers pass the full package name (e.g. provider: 'strapi-provider-upload-google-cloud-storage') + providerOptions: { + accessKeyId: env('AWS_ACCESS_KEY_ID'), + secretAccessKey: env('AWS_ACCESS_SECRET'), + region: env('AWS_REGION'), + params: { + Bucket: env('AWS_BUCKET'), + }, + }, + }, + }, + // ... +}); +``` + +Strapi has a default Security Middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. + +::: + +::: tab Email + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill') + providerOptions: { + apiKey: env('SENDGRID_API_KEY'), + }, + settings: { + defaultFrom: 'juliasedefdjian@strapi.io', + defaultReplyTo: 'juliasedefdjian@strapi.io', + testAddress: 'juliasedefdjian@strapi.io', + }, + }, + }, + // ... +}); +``` + +Keep in mind that: + +* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md). +* Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js` file is in the correct folder. +* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test. See: [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates). + +::: + +### Configuration per environment + +When configuring your provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. + +You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the default configuration. + +## Creating providers + +To implement your own custom provider you must [create a Node.js module](https://docs.npmjs.com/creating-node-js-modules). + +The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins: + +::: tab Upload + +```js +module.exports = { + init(providerOptions) { + // init your provider if necessary + + return { + upload(file) { + // upload the file in the provider + // file content is accessible by `file.buffer` + }, + uploadStream(file) { + // upload the file in the provider + // file content is accessible by `file.stream` + }, + delete(file) { + // delete the file in the provider + }, + }; + }, +}; +``` +::: + +::: tab Email + +```js +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 + +::: + +See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. + +After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. + +### Local providers + +If you want to create your own provider without publishing it on **npm** you can follow these steps: + +1. Create a `providers` folder in your application. +2. Create your provider (e.g. `./providers/strapi-provider--`) +3. Then update your `package.json` to link your `strapi-provider--` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. + +```json +{ + ... + "dependencies": { + ... + "strapi-provider--": "file:providers/strapi-provider--", + ... + } +} +``` + +4. Update your `./config/plugins.js` file to [configure the provider](#configuring-providers). +5. Finally, run `yarn install` or `npm install` to install your new custom provider. \ No newline at end of file From e9b12f3193ccf2f0eaae298d0f0714dfb7636023 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 21 Jun 2022 15:18:39 +0200 Subject: [PATCH 08/74] fix tabs --- docs/developer-docs/latest/development/using-providers.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index 1dadc77872..ecf263ad5a 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -54,6 +54,8 @@ Each provider will have different configuration settings available, review the r Below are example configurations for the Upload and Email plugins. +:::: tabs card + ::: tab Upload ```js @@ -112,6 +114,8 @@ Keep in mind that: ::: +:::: + ### Configuration per environment When configuring your provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. @@ -124,6 +128,8 @@ To implement your own custom provider you must [create a Node.js module](https:/ The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins: +:::: tabs card + ::: tab Upload ```js @@ -169,6 +175,8 @@ In the send function you will have access to: ::: +:::: + See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. From c52be49da0825006dd56e92c73634095b35a4ac8 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 21 Jun 2022 15:51:27 +0200 Subject: [PATCH 09/74] rework text --- docs/developer-docs/latest/plugins/email.md | 395 +------------------- 1 file changed, 2 insertions(+), 393 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 74611af0b4..e08eb73d28 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,14 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. - -## Setup an email provider - -By default Strapi provides a local email system ([sendmail](https://www.npmjs.com/package/sendmail)). 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. - - - +The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. [`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider, the [provider documentation](link) has instructions for changing providers or creating a new email provider. ## Programmatic usage @@ -71,347 +64,6 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -## Configure the plugin - -By default Strapi provides a local email system ([sendmail](https://www.npmjs.com/package/sendmail)). 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. - -The Strapi team maintains the following providers: - -- [Amazon SES](https://www.npmjs.com/package/@strapi/provider-email-amazon-ses) -- [Mailgun](https://www.npmjs.com/package/@strapi/provider-email-mailgun) -- [Nodemailer](https://www.npmjs.com/package/@strapi/provider-email-nodemailer) -- [SendGrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid) -- [Sendmail](https://www.npmjs.com/package/@strapi/provider-email-sendmail) - -You can also find additional community maintained providers on [NPM](https://www.npmjs.com/). - -To install a new provider run: - - - - -```sh -npm install @strapi/provider-email-sendgrid --save -``` - - - -```sh -yarn add @strapi/provider-email-sendgrid --save -``` - - - - -### 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](https://www.npmjs.com/package/@strapi/provider-email-sendgrid). - -:::: tabs card - -::: tab SENDGRID - - - -```js -//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', - }, - }, - }, - // ... -}); -``` - - - - -```js -//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', - }, - }, - }, - // ... -}); - -``` - - - - -::: - -::: tab AMAZON-SES - - - -```js -//path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'amazon-ses', - providerOptions: { - key: env('AWS_SES_KEY'), - secret: env('AWS_SES_SECRET'), - amazon: 'https://email.us-east-1.amazonaws.com', - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` - - - - -```js -//path: ./config/plugins.ts - -export default ({ env }) => ({ - // ... - email: { - config: { - provider: 'amazon-ses', - providerOptions: { - key: env('AWS_SES_KEY'), - secret: env('AWS_SES_SECRET'), - amazon: 'https://email.us-east-1.amazonaws.com', - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); - -``` - - - - -::: - -::: tab MAILGUN - - - -```js -//path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'mailgun', - providerOptions: { - apiKey: env('MAILGUN_API_KEY'), - domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains - host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` - - - - -```js -//path: ./config/plugins.ts - -export default ({ env }) => ({ - // ... - email: { - config: { - provider: 'mailgun', - providerOptions: { - apiKey: env('MAILGUN_API_KEY'), - domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains - host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); - -``` - - - - -::: - -::: tab NODEMAILER - - - -```js -//path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'nodemailer', - providerOptions: { - host: env('SMTP_HOST', 'smtp.example.com'), - port: env('SMTP_PORT', 587), - auth: { - user: env('SMTP_USERNAME'), - pass: env('SMTP_PASSWORD'), - }, - // ... any custom nodemailer options - }, - settings: { - defaultFrom: 'hello@example.com', - defaultReplyTo: 'hello@example.com', - }, - }, - }, - // ... -}); - -``` - - - - -```js -//path: ./config/plugins.ts - -export default ({ env }) => ({ - // ... - email: { - config: { - provider: 'nodemailer', - providerOptions: { - host: env('SMTP_HOST', 'smtp.example.com'), - port: env('SMTP_PORT', 587), - auth: { - user: env('SMTP_USERNAME'), - pass: env('SMTP_PASSWORD'), - }, - // ... any custom nodemailer options - }, - settings: { - defaultFrom: 'hello@example.com', - defaultReplyTo: 'hello@example.com', - }, - }, - }, - // ... -}); - - -``` - - - - -::: - -::: tab SENDMAIL - - - -```js -//path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'sendmail', - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); - - -``` - - - - -```js -//path: ./config/plugins.ts - -export default ({ env }) => ({ - // ... - email: { - config: { - provider: 'sendmail', - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); - - -``` - - - - -::: - -:::: ::: 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](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) @@ -426,50 +78,7 @@ When testing the new email provider with those two email templates created durin More info here: [Configure templates Locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates) ::: -## Create new provider - -Default template - -```js -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 (e.g. `./providers/strapi-provider-email-[...]/...`) -- Then update your `package.json` to link your `strapi-provider-email-[...]` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. - -```json -{ - ... - "dependencies": { - ... - "strapi-provider-email-[...]": "file:providers/strapi-provider-email-[...]", - ... - } -} -``` - -- Finally, run `yarn install` or `npm install` to install your new custom provider. - -## Troubleshooting +## Fix common problems You received an `Auth.form.error.email.invalid` error even though the email is valid and exists in the database. From d2fac4d3ebbbb8d4b9a63c7465b752da43e396c1 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 21 Jun 2022 15:54:50 +0200 Subject: [PATCH 10/74] start programmatic use section --- docs/developer-docs/latest/plugins/email.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index e08eb73d28..e7be88b952 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,16 +6,19 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or external providers such as **Sendgrid**. Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. [`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider, the [provider documentation](link) has instructions for changing providers or creating a new email provider. +The Email plugin enables applications to send email from a server or [external providers](link). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. + +[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider, the [provider documentation](link) has instructions for changing providers or creating a new email provider. + +## Configure the plugin + +something here or is it covered in providers? ## 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** +To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. ```js await strapi.plugins['email'].services.email.send({ From 7718325b1e7286d3cd784e31a06a9c8c5e6e6be8 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 21 Jun 2022 16:29:47 +0200 Subject: [PATCH 11/74] Rework the email template section --- docs/developer-docs/latest/plugins/email.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index e7be88b952..02d34b43bf 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -14,7 +14,7 @@ The Email plugin enables applications to send email from a server or [external p something here or is it covered in providers? -## Programmatic usage +## Programmatic usage ### Send an email - `.send()` @@ -27,7 +27,7 @@ await strapi.plugins['email'].services.email.send({ cc: 'helenedarroze@strapi.io', bcc: 'ghislainearabian@strapi.io', replyTo: 'annesophiepic@strapi.io', - subject: 'Use strapi email provider successfully', + subject: 'The Strapi email provider worked successfully', text: 'Hello world!', html: 'Hello world!', }); @@ -35,23 +35,22 @@ await strapi.plugins['email'].services.email.send({ ### 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 compiles the email and then sends it. The function has the following parameters: +The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The service compiles the email from the available properties and then sends the email. The function has the following parameters: -| 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](https://lodash.com/docs/4.17.15#template) | object | `{}` | -| `data` | Object that contains the data used to compile the templates | object | `{}` | +| 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`. | `object` | {} | +| `data` | Contains the data used to compile the templates. | `object` | {} | **Example** ```js const emailTemplate = { subject: 'Welcome <%= user.firstname %>', - text: `Welcome on mywebsite.fr! + text: `Welcome to mywebsite.fr! Your account is now linked with: <%= user.email %>.`, - html: `

Welcome on mywebsite.fr!

+ html: `

Welcome to mywebsite.fr!

Your account is now linked with: <%= user.email %>.

`, }; From b1f25815d63c8a62368435d71534daa72750017c Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 21 Jun 2022 17:41:49 +0200 Subject: [PATCH 12/74] various changes --- docs/developer-docs/latest/plugins/email.md | 28 ++++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 02d34b43bf..3bc206f515 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,17 +6,17 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or [external providers](link). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. +The Email plugin enables applications to send email from a server or [external providers](link). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. -[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider, the [provider documentation](link) has instructions for changing providers or creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment, but has limited functionality in the production environment and another provider is likely preferable. The [provider documentation](link) has instructions for changing providers or creating a new email provider. ## Configure the plugin something here or is it covered in providers? -## Programmatic usage +## Programmatic usage -### Send an email - `.send()` +### Send an email with backend customization To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. @@ -33,7 +33,7 @@ await strapi.plugins['email'].services.email.send({ }); ``` -### Send an email using a template - `.sendTemplatedEmail()` +### Send an email using a template The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The service compiles the email from the available properties and then sends the email. The function has the following parameters: @@ -43,7 +43,7 @@ The email plugin provides the function `sendTemplatedEmail` to compose email fro | `emailTemplate` | Contains email content properties: `subject`, `text`, and `html`. | `object` | {} | | `data` | Contains the data used to compile the templates. | `object` | {} | -**Example** + ```js const emailTemplate = { @@ -66,20 +66,24 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` +### Send email using lifecycle hooks + +[Lifecycle hooks] can be used to trigger an email based on administrator actions in the admin panel. For example, an editor could receive an email each time an author submits new content. -::: 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](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) -::: -::: 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](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates) ::: + + + + + + + ## Fix common problems You received an `Auth.form.error.email.invalid` error even though the email is valid and exists in the database. From 2311f368bdf528b3032109f62873c646b4c9ac0a Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 21 Jun 2022 17:57:11 +0200 Subject: [PATCH 13/74] Add code example for lifecycle hook in admin panel --- docs/developer-docs/latest/plugins/email.md | 22 ++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 3bc206f515..48c1d09577 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -68,9 +68,29 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ### Send email using lifecycle hooks -[Lifecycle hooks] can be used to trigger an email based on administrator actions in the admin panel. For example, an editor could receive an email each time an author submits new content. +[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. For example, an editor can receive an email each time an author submits new content. +```jsx +//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: 'kai@strapi.io', + from: 'kai@strapi.io', + subject: 'test', + text: '${alertMessage}' + }) + } catch(err) { + console.log(err); + } + } +} +``` ::: 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. From 03b4b6be37e642fa46103e56755cb27754adc5dc Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 08:11:19 +0200 Subject: [PATCH 14/74] add temp links to new providers page --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 48c1d09577..1457947c84 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,9 +6,9 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or [external providers](link). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. +The Email plugin enables applications to send email from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. -[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment, but has limited functionality in the production environment and another provider is likely preferable. The [provider documentation](link) has instructions for changing providers or creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment, but has limited functionality in the production environment and another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. ## Configure the plugin From 125605692c08b2b10dd680af9601f88411441a98 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 08:32:01 +0200 Subject: [PATCH 15/74] delete configure the plugin --- docs/developer-docs/latest/plugins/email.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 1457947c84..e895593cb5 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,9 +10,6 @@ The Email plugin enables applications to send email from a server or [external p [`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment, but has limited functionality in the production environment and another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. -## Configure the plugin - -something here or is it covered in providers? ## Programmatic usage From 2a58a11939b7547c7ac47cebee458d53dbda657b Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 13:36:20 +0200 Subject: [PATCH 16/74] change wording about SendMail --- docs/developer-docs/latest/plugins/email.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index e895593cb5..287e6e1f46 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -8,12 +8,9 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html The Email plugin enables applications to send email from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. -[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment, but has limited functionality in the production environment and another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment but is not production-ready, another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. - -## Programmatic usage - -### Send an email with backend customization +## Send an email with backend customization To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. @@ -30,7 +27,7 @@ await strapi.plugins['email'].services.email.send({ }); ``` -### Send an email using a template +## Send an email using a template The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The service compiles the email from the available properties and then sends the email. The function has the following parameters: @@ -63,7 +60,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -### Send email using lifecycle hooks +## Send email using lifecycle hooks [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. For example, an editor can receive an email each time an author submits new content. From 08334702b6d20bfff61bce308eb92c3cdc2e9161 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 14:23:40 +0200 Subject: [PATCH 17/74] finalize intro topics --- docs/developer-docs/latest/plugins/email.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 287e6e1f46..a5d9062124 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,9 +6,13 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation below provides examples for how to configure the email plugin and examples of controllers, routes, and lifecycle hooks to implement programmatic email. +The Email plugin enables applications to send email from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation provides examples for how to configure the email plugin and examples of controllers and lifecycle hooks to implement programmatic email. -[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi email plugin. It provides functionality for the local development environment but is not production-ready, another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. + +The email templates located in the Users and Permissions plugin are documented with + +Programatic emails are triggered by user actions such as clicking on a forgot password link. ## Send an email with backend customization @@ -86,18 +90,13 @@ module.exports = { } ``` + - ## Fix common problems You received an `Auth.form.error.email.invalid` error even though the email is valid and exists in the database. @@ -136,3 +135,5 @@ Error: SMTP code:550 msg:550-5.7.1 [87.88.179.13] The IP you're using to send ma 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. + +--> \ No newline at end of file From b282c4b7f3ef01775f295f24c0f115cfbf6d1b7e Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 15:28:43 +0200 Subject: [PATCH 18/74] remove unused content --- docs/developer-docs/latest/plugins/email.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index a5d9062124..55af4b93ea 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,10 +10,6 @@ The Email plugin enables applications to send email from a server or [external p [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. -The email templates located in the Users and Permissions plugin are documented with - -Programatic emails are triggered by user actions such as clicking on a forgot password link. - ## Send an email with backend customization To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. From 0165e22548a10a381a6a5a1cecd6d3aef8e33a80 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 15:59:47 +0200 Subject: [PATCH 19/74] Cleanup code examples and remove troubleshooting section --- docs/developer-docs/latest/plugins/email.md | 85 ++++++--------------- 1 file changed, 23 insertions(+), 62 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 55af4b93ea..69fa0d2d4c 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,26 +10,34 @@ The Email plugin enables applications to send email from a server or [external p [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. -## Send an email with backend customization +## Send an email using custom a controller or service To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. + + ```js -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: 'The Strapi email provider worked successfully', - text: 'Hello world!', - html: 'Hello world!', +//path: ./src/api/{api name}/controllers/{api name}.js + +const { createCoreController } = require('@strapi/strapi').factories; + +module.exports = createCoreController('api::restaurant.restaurant', ({ strapi }) => ({ + 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: 'The Strapi email provider worked successfully', + text: 'Hello world!', + html: 'Hello world!', + }), }); ``` ## Send an email using a template -The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The service compiles the email from the available properties and then sends the email. The function has the following parameters: +The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: | Parameter | Description | Type | Default | |-----------------|---------------------------------------------------------------------------------|----------|---------| @@ -37,7 +45,8 @@ The email plugin provides the function `sendTemplatedEmail` to compose email fro | `emailTemplate` | Contains email content properties: `subject`, `text`, and `html`. | `object` | {} | | `data` | Contains the data used to compile the templates. | `object` | {} | - +To use the `sendTemplatedEmail` function add a constant `emailTemplate` above the function. + ```js const emailTemplate = { @@ -79,57 +88,9 @@ module.exports = { subject: 'test', text: '${alertMessage}' }) - } catch(err) { - console.log(err); - } - } -} -``` - - \ No newline at end of file +## Find other email documentation From 4105d5b4d80da24a45fbf680f9329cf086ad71e9 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 16:24:00 +0200 Subject: [PATCH 20/74] comment out last section for now --- docs/developer-docs/latest/plugins/email.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 69fa0d2d4c..cfc2acf2f4 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -93,4 +93,12 @@ module.exports = { } ``` + \ No newline at end of file From 64ff396fe279af36a90291fe15004dbea89c2078 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 17:02:46 +0200 Subject: [PATCH 21/74] fix grammar --- docs/developer-docs/latest/plugins/email.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index cfc2acf2f4..a80351f964 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -12,11 +12,12 @@ The Email plugin enables applications to send email from a server or [external p ## Send an email using custom a controller or service -To trigger an email in response to a user input add the following function to a custom controller or service. The function will utilize the email provider enabled in the `plugins.js` configuration file. +To trigger an email in response to a user input add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. ```js + //path: ./src/api/{api name}/controllers/{api name}.js const { createCoreController } = require('@strapi/strapi').factories; @@ -43,12 +44,15 @@ The email plugin provides the function `sendTemplatedEmail` to compose email fro |-----------------|---------------------------------------------------------------------------------|----------|---------| | `emailOptions` | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc`. | `object` | {} | | `emailTemplate` | Contains email content properties: `subject`, `text`, and `html`. | `object` | {} | -| `data` | Contains the data used to compile the templates. | `object` | {} | +| `data` | Contains data used to compile the templates. | `object` | {} | To use the `sendTemplatedEmail` function add a constant `emailTemplate` above the function. ```js + +//path: ./src/api/{api name}/controllers/{api name}.js + const emailTemplate = { subject: 'Welcome <%= user.firstname %>', text: `Welcome to mywebsite.fr! From c0687d65efe2a7f2a5cfb0aedbe0d54fc500d90a Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 17:28:23 +0200 Subject: [PATCH 22/74] add html tags to table --- docs/developer-docs/latest/plugins/email.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index a80351f964..0adc920fd4 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -42,8 +42,8 @@ The email plugin provides the function `sendTemplatedEmail` to compose email fro | 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`. | `object` | {} | +| `emailOptions` | Contains email addressing properties:

  • `to`
  • `from`
  • `replyTo`
  • `cc`
  • `bcc`
| `object` | {} | +| `emailTemplate` | Contains email content properties:
  • `subject`
  • `text`
  • `html`
| `object` | {} | | `data` | Contains data used to compile the templates. | `object` | {} | To use the `sendTemplatedEmail` function add a constant `emailTemplate` above the function. @@ -66,7 +66,7 @@ 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, + emailTemplate, { user: _.pick(user, ['username', 'email', 'firstname', 'lastname']), } From 3f488f11affafc25e82174913f0e4c45ada40583 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 22 Jun 2022 18:40:57 +0200 Subject: [PATCH 23/74] small content edit --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 0adc920fd4..65d279c28d 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -89,7 +89,7 @@ module.exports = { await strapi.plugins['email'].services.email.send({ to: 'kai@strapi.io', from: 'kai@strapi.io', - subject: 'test', + subject: 'New content posted', text: '${alertMessage}' }) } From a645e6e729617b2e2d1d2cf84df4329703e12b4b Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Thu, 23 Jun 2022 14:26:03 +0200 Subject: [PATCH 24/74] Adding Sentry plugin doc --- docs/.vuepress/config/sidebar-developer.js | 1 + docs/developer-docs/latest/plugins/sentry.md | 140 +++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 docs/developer-docs/latest/plugins/sentry.md diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 9a8dbf3b8b..9ee5ec8833 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -425,6 +425,7 @@ const developer = [ ['/developer-docs/latest/plugins/users-permissions', 'Users & Permissions'], ['/developer-docs/latest/plugins/email', 'Email'], ['/developer-docs/latest/plugins/upload', 'Upload'], + ['/developer-docs/latest/plugins/sentry', 'Sentry'], ['/developer-docs/latest/plugins/documentation', 'API Documentation'], ], sidebarDepth: 1, diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md new file mode 100644 index 0000000000..cd059c1d2e --- /dev/null +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -0,0 +1,140 @@ +--- +title: Sentry - Strapi Developer Docs +description: Send email from your server or externals providers. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html +--- + +# Sentry + +This plugin enables you to track errors in your Strapi application using [Sentry](https://sentry.io/welcome/). + +By using the Sentry plugin you can: + +* Initialize a Sentry instance upon startup of a Strapi application +* Send Strapi application errors as events to Sentry +* Include additional metadata in Sentry events to assist in debugging +* Expose a [global Sentry service](#global-sentry-service) + +## Installation + +Install the Sentry plugin by adding the dependency to your Strapi application as follows: + + + + +```sh +npm install @strapi/plugin-sentry +``` + + + +```sh +yarn add @strapi/plugin-sentry +``` + + + + +Then you must [configure](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. + +## Configuration + +Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: + +| Property | Type | Default Value | Description | +| -------------- | -------------- |------------ | +| `dsn` | string | `null` | Your Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). | +| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry. | +| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization. See the official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for all available options. | + +An example configuration: + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + sentry: { + enabled: true, + config: { + dsn: env('SENTRY_DSN'), + sendMetadata: true, + }, + }, + // ... +}); +``` + +### Environment configuration + +Using the `env` utility, you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + sentry: { + enabled: env('NODE_ENV') === 'production', + }, + // ... +}); +``` + +## Global Sentry service + +After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows: + +```js +const sentryService = strapi.plugin('sentry').service('sentry'); +``` + +This service exposes the following methods: + +| Method | Description | Parameters | +| ------ | ----------- | ---------- | +| `sendError` | Manually send errors to Sentry. |
  • error: The error to be sent.
  • configureScope: Optional. Enables you to customize the error event.


    • See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | +| `getInstance` | Used for direct access to the Sentry instance. | | + +### Examples + +:::: tabs card + +::: tab sendError + +```js +try { + // Your code here +} catch (error) { + // Either send a simple error + strapi + .plugin('sentry') + .service('sentry') + .sendError(error); + + // Or send an error with a customized Sentry scope + strapi + .plugin('sentry') + .service('sentry') + .sendError(error, (scope, sentryInstance) => { + // Customize the scope here + scope.setTag('my_custom_tag', 'Tag value'); + }); + throw error; +} +``` + +::: + +::: tab getInstance + +```js +const sentryInstance = strapi + .plugin('sentry') + .service('sentry') + .getInstance(); +``` + +::: + +:::: \ No newline at end of file From 6f4507e633cdf8cbce6e2a3b38cdbf1e2314d813 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Thu, 23 Jun 2022 14:34:57 +0200 Subject: [PATCH 25/74] fix tables --- docs/developer-docs/latest/plugins/sentry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md index cd059c1d2e..1ecdcd3112 100644 --- a/docs/developer-docs/latest/plugins/sentry.md +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -42,7 +42,7 @@ Then you must [configure](#configuration) the plugin to enable your Strapi appli Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: | Property | Type | Default Value | Description | -| -------------- | -------------- |------------ | +| -------- | ---- | ------------- |------------ | | `dsn` | string | `null` | Your Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). | | `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry. | | `init` | object | `{}` | A config object that is passed directly to Sentry during initialization. See the official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for all available options. | @@ -93,7 +93,7 @@ This service exposes the following methods: | Method | Description | Parameters | | ------ | ----------- | ---------- | -| `sendError` | Manually send errors to Sentry. |
    • error: The error to be sent.
    • configureScope: Optional. Enables you to customize the error event.


      • See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | +| `sendError` | Manually send errors to Sentry. |
      • error: The error to be sent.
      • configureScope: Optional. Enables you to customize the error event.

        • See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | | `getInstance` | Used for direct access to the Sentry instance. | | ### Examples From 390bb41068391ed643b188f7529b19bdcfe08dcf Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Fri, 24 Jun 2022 16:47:32 +0200 Subject: [PATCH 26/74] fix controller code example --- docs/developer-docs/latest/plugins/email.md | 23 +++++++-------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 65d279c28d..2d4b734783 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -12,28 +12,22 @@ The Email plugin enables applications to send email from a server or [external p ## Send an email using custom a controller or service -To trigger an email in response to a user input add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. - - +To trigger an email in response to a user input add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js //path: ./src/api/{api name}/controllers/{api name}.js -const { createCoreController } = require('@strapi/strapi').factories; - -module.exports = createCoreController('api::restaurant.restaurant', ({ strapi }) => ({ 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: 'The Strapi email provider worked successfully', + 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!', }), -}); ``` ## Send an email using a template @@ -46,8 +40,7 @@ The email plugin provides the function `sendTemplatedEmail` to compose email fro | `emailTemplate` | Contains email content properties:
        • `subject`
        • `text`
        • `html`
        | `object` | {} | | `data` | Contains data used to compile the templates. | `object` | {} | -To use the `sendTemplatedEmail` function add a constant `emailTemplate` above the function. - +To use the `sendTemplatedEmail` function define the `emailTemplate` object . ```js From 44c19e0f0fb15965355adbb120d40781e0041f4e Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 07:49:09 +0200 Subject: [PATCH 27/74] updated some language --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 2d4b734783..4523b1b0a1 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -12,7 +12,7 @@ The Email plugin enables applications to send email from a server or [external p ## Send an email using custom a controller or service -To trigger an email in response to a user input add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js @@ -68,7 +68,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ## Send email using lifecycle hooks -[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. For example, an editor can receive an email each time an author submits new content. +[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. For example, an editor can receive an email each time an author creates a new content entry in the Content Manager. ```jsx From f1b64b70b6e7458da3ca8b2e3a2250736e76d71b Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 08:05:09 +0200 Subject: [PATCH 28/74] update lifecycle hook section --- docs/developer-docs/latest/plugins/email.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 4523b1b0a1..3b12125cb5 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send email from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation provides examples for how to configure the email plugin and examples of controllers and lifecycle hooks to implement programmatic email. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation provides examples for how to configure the email plugin and examples of controllers and lifecycle hooks to implement programmatic email. [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. @@ -32,7 +32,7 @@ To trigger an email in response to a user action add the following function to a ## Send an email using a template -The email plugin provides the function `sendTemplatedEmail` to compose email from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: +The email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: | Parameter | Description | Type | Default | |-----------------|---------------------------------------------------------------------------------|----------|---------| @@ -66,9 +66,9 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -## Send email using lifecycle hooks +## Send an email using a lifecycle hook -[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. For example, an editor can receive an email each time an author creates a new content entry in the Content Manager. +[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. 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 on the **Save** event when adding a new entry to the specified collection type. ```jsx From 5df7c3b53b9c0692b5b3e77e614d2309230e912a Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 08:29:51 +0200 Subject: [PATCH 29/74] improve spelling an grammar --- docs/developer-docs/latest/plugins/email.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 3b12125cb5..14a3fd6893 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,13 +6,13 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programatic emails. The documentation provides examples for how to configure the email plugin and examples of controllers and lifecycle hooks to implement programmatic email. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. ## Send an email using custom a controller or service -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function will utilize the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js @@ -40,7 +40,7 @@ The email plugin provides the function `sendTemplatedEmail` to compose emails fr | `emailTemplate` | Contains email content properties:
        • `subject`
        • `text`
        • `html`
        | `object` | {} | | `data` | Contains data used to compile the templates. | `object` | {} | -To use the `sendTemplatedEmail` function define the `emailTemplate` object . +To use the `sendTemplatedEmail` function define the `emailTemplate` object. ```js From 19a65472c67667aea27cd2eba144b77b08086386 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 09:17:25 +0200 Subject: [PATCH 30/74] improve misc things --- docs/developer-docs/latest/plugins/email.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 14a3fd6893..af503d5675 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -37,10 +37,10 @@ The email plugin provides the function `sendTemplatedEmail` to compose emails fr | Parameter | Description | Type | Default | |-----------------|---------------------------------------------------------------------------------|----------|---------| | `emailOptions` | Contains email addressing properties:
        • `to`
        • `from`
        • `replyTo`
        • `cc`
        • `bcc`
        | `object` | {} | -| `emailTemplate` | Contains email content properties:
        • `subject`
        • `text`
        • `html`
        | `object` | {} | +| `emailTemplate` | Contains email content properties using [Lodash string templates](https://lodash.com/docs/4.17.15#template):
        • `subject`
        • `text`
        • `html`
        | `object` | {} | | `data` | Contains data used to compile the templates. | `object` | {} | -To use the `sendTemplatedEmail` function define the `emailTemplate` object. +To use the `sendTemplatedEmail` function define the `emailTemplate` object and insert the function into a controller or service. ```js @@ -57,7 +57,7 @@ const emailTemplate = { await strapi.plugins['email'].services.email.sendTemplatedEmail( { to: user.email, - // from: is not specified, so it's the defaultFrom that will be used instead + // from: is not specified, the defaultFrom is used. }, emailTemplate, { @@ -89,13 +89,3 @@ module.exports = { } } ``` - - \ No newline at end of file From 5b969741f0d74402e0c186339f48b1f39e0e1d31 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 09:28:35 +0200 Subject: [PATCH 31/74] improve the introduction --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index af503d5675..cb542c97d3 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,9 +6,9 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin to be configured in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. -[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers or creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. ## Send an email using custom a controller or service From 49007b01fb6ecfed60f70ebed6dbef340f69d158 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 10:01:13 +0200 Subject: [PATCH 32/74] update table and misc improvements --- docs/developer-docs/latest/plugins/email.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index cb542c97d3..c5cee59116 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires the plugin to be configured in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires a provider configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. @@ -34,13 +34,13 @@ To trigger an email in response to a user action add the following function to a The email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: -| Parameter | Description | Type | Default | -|-----------------|---------------------------------------------------------------------------------|----------|---------| -| `emailOptions` | Contains email addressing properties:
        • `to`
        • `from`
        • `replyTo`
        • `cc`
        • `bcc`
        | `object` | {} | -| `emailTemplate` | Contains email content properties using [Lodash string templates](https://lodash.com/docs/4.17.15#template):
        • `subject`
        • `text`
        • `html`
        | `object` | {} | -| `data` | Contains data used to compile the templates. | `object` | {} | +| 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](https://lodash.com/docs/4.17.15#template) | `object` | {} | +| `data` | Contains the data used to compile the templates | `object` | {} | -To use the `sendTemplatedEmail` function define the `emailTemplate` object and insert the function into a controller or service. +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. ```js @@ -70,7 +70,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. 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 on the **Save** event when adding a new entry to the specified collection type. -```jsx +```js //path: ./src/api/[api-name]]/content-types/[content-type-name]/lifecycles.js From 7f1391add5a214481a85cb0ee5fdeed477662cd4 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 27 Jun 2022 14:23:34 +0200 Subject: [PATCH 33/74] improved lifecycle hook text --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index c5cee59116..2566310f32 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -68,11 +68,11 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ## Send an email using a lifecycle hook -[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. 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 on the **Save** event when adding a new entry to the specified collection type. +[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. 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. ```js -//path: ./src/api/[api-name]]/content-types/[content-type-name]/lifecycles.js +//path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js module.exports = { async afterCreate(event) { From c6f7dd107e72d3749263e563219bcd657f0052c2 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 29 Jun 2022 12:20:25 +0200 Subject: [PATCH 34/74] Fix email plugin caps --- docs/developer-docs/latest/plugins/email.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 2566310f32..12ad480bdc 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,11 +6,11 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires a provider configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the email plugin to send emails using controllers and lifecycle hooks. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires a provider configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the Email plugin to send emails using controllers and lifecycle hooks. -[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. +[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. -## Send an email using custom a controller or service +## Send an email using a controller or service To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. @@ -24,7 +24,7 @@ To trigger an email in response to a user action add the following function to a cc: 'valid email address', bcc: 'valid email address', replyTo: 'valid email address', - subject: 'The Strapi email plugin worked successfully', + subject: 'The Strapi Email plugin worked successfully', text: 'Hello world!', html: 'Hello world!', }), @@ -32,7 +32,7 @@ To trigger an email in response to a user action add the following function to a ## Send an email using a template -The email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: +The Email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: | Parameter | Description | Type | Default | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| From d91c12464f24494aaa171cb8fe5060fcd99b35fa Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 29 Jun 2022 14:31:08 +0200 Subject: [PATCH 35/74] fix --- docs/developer-docs/latest/plugins/email.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 12ad480bdc..33496314af 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -80,12 +80,14 @@ module.exports = { try{ await strapi.plugins['email'].services.email.send({ - to: 'kai@strapi.io', - from: 'kai@strapi.io', - subject: 'New content posted', - text: '${alertMessage}' + to: 'shaun.brown@strapi.io', + from: 'shaun.brown@strapi.io', + subject: 'test', + text: '${welcomeMessage}' }) - } + } catch(err) { + console.log(err); + } } } ``` From 5f988716be3894c959ccc0b3bcd2b1ef6cb7680b Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 29 Jun 2022 14:46:55 +0200 Subject: [PATCH 36/74] Add missing closing
      that prevented VuePress rendering --- docs/developer-docs/latest/plugins/sentry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md index 1ecdcd3112..0db8a123af 100644 --- a/docs/developer-docs/latest/plugins/sentry.md +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -93,7 +93,7 @@ This service exposes the following methods: | Method | Description | Parameters | | ------ | ----------- | ---------- | -| `sendError` | Manually send errors to Sentry. |
      • error: The error to be sent.
      • configureScope: Optional. Enables you to customize the error event.

        • See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | +| `sendError` | Manually send errors to Sentry. |
        • error: The error to be sent.
        • configureScope: Optional. Enables you to customize the error event.

        See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | | `getInstance` | Used for direct access to the Sentry instance. | | ### Examples From 50c65c5d84a56bfab7159b455bad4f3b5f477ffd Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Wed, 29 Jun 2022 17:53:41 +0200 Subject: [PATCH 37/74] add bullet points --- docs/developer-docs/latest/plugins/email.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 33496314af..88e41000eb 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,13 +6,18 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires a provider configuration in a `plugins.js` file and an event that triggers an email, such as a custom controller for external requests or a lifecycle hook for requests inside the admin panel. Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the Email plugin to send emails using controllers and lifecycle hooks. +The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires: -[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. +- a provider configuration in a `plugins.js` file, +- an event that triggers an email, such as a controller for external requests or a lifecycle hook for requests inside the admin panel. + + Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the Email plugin to send emails using controllers and lifecycle hooks. + +[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable for production stage applications. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. ## Send an email using a controller or service -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). Since both controllers and services access The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js From a73a9a7c024cae3ad8d356ab3c35b377554f8850 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 30 Jun 2022 07:53:35 +0200 Subject: [PATCH 38/74] remove unnecessary fragment --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 88e41000eb..5a30606957 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -17,7 +17,7 @@ The Email plugin enables applications to send emails from a server or [external ## Send an email using a controller or service -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). Since both controllers and services access The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js From 9e3f414ae8f5d0bbdf6926d5697596849c3074d5 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 30 Jun 2022 08:03:58 +0200 Subject: [PATCH 39/74] rework intro --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 5a30606957..f7a9b92d3a 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -11,7 +11,7 @@ The Email plugin enables applications to send emails from a server or [external - a provider configuration in a `plugins.js` file, - an event that triggers an email, such as a controller for external requests or a lifecycle hook for requests inside the admin panel. - Data from the Content Manager can also be populated into email templates using the function `sendTemplatedEmail` to streamline programmatic emails. This documentation provides examples of how to use the Email plugin to send emails using controllers and lifecycle hooks. + 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. [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable for production stage applications. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. @@ -35,7 +35,7 @@ To trigger an email in response to a user action add the following function to a }), ``` -## Send an email using a template +## Send a templated email using a controller or service The Email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: From 8cf2a2ea4ca5e389ff7a77d9119e8e6cdefeb8ef Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Thu, 30 Jun 2022 10:13:25 +0200 Subject: [PATCH 40/74] Update based on feedback --- .../latest/development/using-providers.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index ecf263ad5a..4a642a1f77 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -11,20 +11,20 @@ Certain [plugins](../../../user-docs/latest/plugins/introduction-to-plugins.md) Providers add an extension to the core capabilities of the plugin, for example to upload media files to Rackspace instead of the local server, or using Amazon SES for emails instead of Sendmail. ::: note -Only the [Upload](./upload.md) and [Email](./email.md) plugins are currently designed to work with providers. +Only the [Upload](../plugins/upload.md) and [Email](../plugins/email.md) plugins are currently designed to work with providers. ::: -For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [NPM](https://www.npmjs.com/). +For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [npm](https://www.npmjs.com/). ## Installing providers -Install new providers using `npm` or `yarn` using the format `@strapi/provider-- --save`. +New providers can be installed using `npm` or `yarn` using the following format `@strapi/provider-- --save`. For example: - + ```sh # Install the AWS S3 provider for the Upload plugin npm install @strapi/provider-upload-aws-s3 --save @@ -50,7 +50,7 @@ yarn add @strapi/provider-email-sendgrid --save Newly installed providers are enabled and configured in the `./config/plugins.js` file. If this file does not exist you must create it. -Each provider will have different configuration settings available, review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [NPM](https://www.npmjs.com/) to learn more. +Each provider will have different configuration settings available. Review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [npm](https://www.npmjs.com/) to learn more. Below are example configurations for the Upload and Email plugins. @@ -80,7 +80,7 @@ module.exports = ({ env }) => ({ }); ``` -Strapi has a default Security Middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. +Strapi has a default `security` middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. ::: @@ -108,9 +108,9 @@ module.exports = ({ env }) => ({ Keep in mind that: -* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md). +* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js` (See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md)). * Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js` file is in the correct folder. -* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test. See: [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates). +* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test (See [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates)). ::: @@ -177,13 +177,13 @@ In the send function you will have access to: :::: -See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. +You can review the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for example implementations. -After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. +After creating your new provider you can [publish it to npm](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. ### Local providers -If you want to create your own provider without publishing it on **npm** you can follow these steps: +If you want to create your own provider without publishing it on npm you can follow these steps: 1. Create a `providers` folder in your application. 2. Create your provider (e.g. `./providers/strapi-provider--`) From d37dd640d3fa952f201487232d0d55cd08c2c56f Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 27 Jun 2022 13:44:57 +0200 Subject: [PATCH 41/74] Update upload.md --- docs/developer-docs/latest/plugins/upload.md | 246 +++++-------------- 1 file changed, 55 insertions(+), 191 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 4ce38efb77..ab41a8a66d 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -6,10 +6,47 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/upload.html # Upload -The `Upload` plugin is used to implement the Media Library available in the admin panel. With it you can upload any kind of file on your server or external providers such as **AWS S3**. +The `Upload` plugin is the backend powering the [Media Library](../../../user-docs/latest/media-library/introduction-to-media-library.md) plugin available by default in the Strapi admin panel. + +Using either the Media Library UI or the upload API directly, you can upload any kind of file for use in your Strapi application. + +By default Strapi provides a [provider](../development/using-providers.md) that uploads files to a local directory. Additional providers are available should you want to upload your files to another location. + +The providers maintained by Strapi include: + +- [Amazon S3](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) +- [Cloudinary](https://www.npmjs.com/package/@strapi/provider-upload-cloudinary) +- [Local](https://www.npmjs.com/package/@strapi/provider-upload-local) +- [Rackspace](https://www.npmjs.com/package/@strapi/provider-upload-rackspace) ## Configuration +This section details configuration options for the default upload provider. If using another provider (e.g. AWS S3 or Rackspace), see the available configuration parameters in that provider's documentation. + +### Local server + +By default Strapi accepts `localServer` configurations for locally uploaded files. These will be passed as the options for [koa-static](https://github.com/koajs/static). + +You can provide them by creating or editing the `./config/plugins.js` file. The example below sets the `max-age` header. + +```js +// path: ./config/plugins.js + +module.exports = ({ env })=>({ + upload: { + config: { + providerOptions: { + localServer: { + maxage: 300000 + }, + }, + }, + }, +}); +``` + +### Max file size + Currently the Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of **200MB**. The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it uses the [`node-formidable`](https://github.com/felixge/node-formidable) library to process files. @@ -36,7 +73,7 @@ module.exports = { }; ``` -### Responsive Images +### Responsive images When the `Enable responsive friendly upload` setting is enabled in the settings panel the plugin will generate the following responsive image sizes: | Name | Largest Dimension | @@ -105,11 +142,13 @@ module.exports = ({ env }) => ({ -## Upload files +## Examples -To upload files to your application. +### Upload files -### Parameters +Upload one or more files to your application. + +The following parameters are accepted: - `files`: The file(s) to upload. The value(s) can be a Buffer or Stream. @@ -166,11 +205,11 @@ const response = await fetch('http://localhost:1337/api/upload', { You have to send FormData in your request body. ::: -## Upload files related to an entry +### Upload entry files -To upload files that will be linked to a specific entry. +Upload one or more files that will be linked to a specific entry. -### Request parameters +The following parameters are accepted: - `files`: The file(s) to upload. The value(s) can be a Buffer or Stream. - `path` (optional): The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). @@ -179,9 +218,7 @@ To upload files that will be linked to a specific entry. - `source` (optional): The name of the plugin where the model is located. - `field`: The field of the entry which the file(s) will be precisely linked to. -### Examples - -The `Restaurant` model attributes: +For example, given the `Restaurant` model attributes: ```json // path: ./src/api/restaurant/content-types/restaurant/schema.json @@ -201,7 +238,7 @@ The `Restaurant` model attributes: } ``` -Code +The corresponding code would be: ```html
        @@ -231,13 +268,11 @@ Code You have to send FormData in your request body. ::: -## Upload file during entry creation +### Upload files at entry creation You can also add files during your entry creation. -### Examples - -The `Restaurant` model attributes: +For example, given the `Restaurant` model attributes: ```json // path: ./src/api/restaurant/content-types/restaurant/schema.json @@ -255,10 +290,9 @@ The `Restaurant` model attributes: } // ... } - ``` -Code +The corresponding code would be: ```html @@ -298,18 +332,17 @@ Code ``` -Your entry data has to be contained in a `data` key and you need to `JSON.stringify` this object. The keys for files, need to be prefixed with `files` (example with a cover attribute: `files.cover`). +Your entry data has to be contained in a `data` key and you need to `JSON.stringify` this object. The keys for files need to be prefixed with `files` (e.g. for a cover attribute: `files.cover`). ::: tip -If you want to upload files for a component, you will have to specify the index of the item you want to add the file to. -Example `files.my_component_name[the_index].attribute_name` +If you want to upload files for a component, you will have to specify the index of the item you want to add the file to: `files.my_component_name[the_index].attribute_name` ::: :::caution You have to send FormData in your request body. ::: -## Models definition +### Models definition Adding a file attribute to a model (or the model of another plugin) is like adding a new association. @@ -364,172 +397,3 @@ In our second example, you can upload and attach multiple pictures to the restau // ... } ``` - -## Using a provider - -By default Strapi provides a provider that uploads files to a local directory. You might want to upload your files to another provider like AWS S3. - -Below are the providers maintained by the Strapi team: - -- [Amazon S3](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) -- [Cloudinary](https://www.npmjs.com/package/@strapi/provider-upload-cloudinary) -- [Local](https://www.npmjs.com/package/@strapi/provider-upload-local) -- [Rackspace](https://www.npmjs.com/package/@strapi/provider-upload-rackspace) - -You can also find additional community maintained providers on [NPM](https://www.npmjs.com/). - -To install a new provider run: - - - - -```sh -npm install @strapi/provider-upload-aws-s3 --save -``` - - - -```sh -yarn add @strapi/provider-upload-aws-s3 -``` - - - - -### Local server - -By default Strapi accepts `localServer` configurations for locally uploaded files. They will be passed as the options for [koa-static](https://github.com/koajs/static). - -You can provide them by create or edit the file at `./config/plugins.js`. The example below set `max-age` header. - -```js -// path: ./config/plugins.js - -module.exports = ({ env })=>({ - upload: { - config: { - providerOptions: { - localServer: { - maxage: 300000 - }, - }, - }, - }, -}); -``` - -### Enabling the provider - -To enable the provider, create or edit the file at `./config/plugins.js` - -::: note -When using community providers, pass the full package name to the `provider` key (e.g. `provider: 'strapi-provider-upload-google-cloud-storage'`). Only Strapi-maintained providers can use the shortcode format (e.g. `provider: 'aws-s3'`). -::: - -```js -// path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - upload: { - config: { - provider: 'aws-s3', - providerOptions: { - accessKeyId: env('AWS_ACCESS_KEY_ID'), - secretAccessKey: env('AWS_ACCESS_SECRET'), - region: env('AWS_REGION'), - params: { - Bucket: env('AWS_BUCKET'), - }, - }, - }, - }, - // ... -}); -``` - -Make sure to read the provider's `README` to know what are the possible parameters. - -:::caution -Strapi has a default Security Middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the provider page or take a look at our [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. -::: - -### Configuration per environment - -When configuring your upload provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. - -You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the one in the default configuration. - -## Create providers - -You can create a Node.js module to implement a custom provider. Read the official documentation [here](https://docs.npmjs.com/creating-node-js-modules). - -Your provider needs to export the following interface: - -```js -module.exports = { - init(providerOptions) { - // init your provider if necessary - - return { - upload(file) { - // upload the file in the provider - // file content is accessible by `file.buffer` - }, - uploadStream(file) { - // upload the file in the provider - // file content is accessible by `file.stream` - }, - delete(file) { - // delete the file in the provider - }, - }; - }, -}; -``` - -:::tip -For performance reasons, the upload plugin will only use the `uploadStream` function if it exists, otherwise it will fallback on the `upload` function. -::: - -You can then publish it to make it available to the community. - -### Create a local provider - -If you want to create your own provider without publishing it on **npm** you can follow these steps: - -1. Create a `./providers/upload-{provider-name}` folder in your root application folder. -2. Create your provider as explained in the [documentation](#create-providers) above. -3. Update your `package.json` to link your `upload-{provider-name}` dependency to point to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your provider: - -```json -// path: ./package.json - -{ - ... - "dependencies": { - ... - "@strapi/provider-upload-{provider-name}": "file:providers/upload-{provider-name}" - ... - } -} -``` - -4. Update the Upload plugin configuration: - -```js -// path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - upload: { - config: { - provider: '{provider-name}', - providerOptions: {}, - }, - }, - // ... -}); -``` - -5. Run `yarn install` or `npm install` to install your new custom provider. From 15c27c92a77f72ccd7c9c1e12906c9d59aa2c652 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 4 Jul 2022 11:09:52 +0200 Subject: [PATCH 42/74] improved various parts --- docs/developer-docs/latest/plugins/email.md | 44 +++++++++++++-------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index f7a9b92d3a..0122b0c84b 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,22 +6,28 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or [external providers](/developer-docs/latest/development/using-providers.md). Successful use of the plugin requires: +The Email plugin enables applications to send emails from a server or external providers. 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 or using a lifecycle hook for admin panel use cases. -- a provider configuration in a `plugins.js` file, -- an event that triggers an email, such as a controller for external requests or a lifecycle hook for requests inside the admin panel. +::: prerequisite - 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. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[ Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +::: + + [`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable for production stage applications. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. -## Send an email using a controller or service +## Sending emails + +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 in the back end To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. ```js -//path: ./src/api/{api name}/controllers/{api name}.js +// e.g. path: ./src/api/{api name}/controllers/{api name}.js await strapi.plugins['email'].services.email.send({ to: 'valid email address', @@ -35,9 +41,9 @@ To trigger an email in response to a user action add the following function to a }), ``` -## Send a templated email using a controller or service +### Using the Send templated email function in the back end -The Email plugin provides the function `sendTemplatedEmail` to compose emails from a template. The function compiles the email from the available properties and then sends the email. The function has the following parameters: +The Email plugin provides 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 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| @@ -45,11 +51,9 @@ The Email plugin provides the function `sendTemplatedEmail` to compose emails fr | `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | {} | | `data` | Contains the data used to compile the templates | `object` | {} | -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. - ```js -//path: ./src/api/{api name}/controllers/{api name}.js +// e.g. path: ./src/api/{api name}/controllers/{api name}.js const emailTemplate = { subject: 'Welcome <%= user.firstname %>', @@ -71,13 +75,19 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -## Send an email using a lifecycle hook +## Using a lifecycle hook to send email from the admin panel + + Another use case for the Email plugin is to trigger an email based on administrator actions in the admin panel using [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#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. -[Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) can be used to trigger an email based on administrator actions in the admin panel. 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 `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](#using-the-send-function-in-the-back-end), with the same available properties. + - Fields from the new content entry can be included in the email using the `text` property and the value `${fieldName}` to indicate which field should be included. ```js -//path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js +// e.g. path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js module.exports = { async afterCreate(event) { @@ -85,9 +95,9 @@ module.exports = { try{ await strapi.plugins['email'].services.email.send({ - to: 'shaun.brown@strapi.io', - from: 'shaun.brown@strapi.io', - subject: 'test', + to: 'a valid email address', + from: 'a valid email address', + subject: 'A new content entry', text: '${welcomeMessage}' }) } catch(err) { From 772881aede6175d94f8eefe0b7a1fed007b21ace Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 4 Jul 2022 12:45:49 +0200 Subject: [PATCH 43/74] add call out and fix titles --- docs/developer-docs/latest/plugins/email.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 0122b0c84b..4a2ab36035 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -14,8 +14,9 @@ The Email plugin requires a provider and a provider configuration in the `plugin ::: - -[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. Another provider is likely preferable for production stage applications. The [provider documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, creating a new email provider, and configuring the `plugins.js` file. +::: note +[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. For production stage applications you need to further configure `Sendmail` or change providers. The [Using providers documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, configuring providers, and creating a new email provider. +::: ## Sending emails @@ -41,7 +42,7 @@ To trigger an email in response to a user action add the following function to a }), ``` -### Using the Send templated email function in the back end +### Using the `sendTemplatedEmail` function in the back end The Email plugin provides 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. @@ -75,13 +76,13 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -## Using a lifecycle hook to send email from the admin panel +### Using 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](/developer-docs/latest/development/backend-customization/models.md#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 code example illustrates a lifecycle hook that runs when a new entry is created in the specified collection type. - - The `afterCreate` lifecycle event is initiated when an administrator clicks the **Save** button in the Content Manager. + - 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](#using-the-send-function-in-the-back-end), with the same available properties. - Fields from the new content entry can be included in the email using the `text` property and the value `${fieldName}` to indicate which field should be included. From 09fc10914fc8b7f82640f4f4840f26abc765dfa4 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 4 Jul 2022 14:26:58 +0200 Subject: [PATCH 44/74] misc improvements --- docs/developer-docs/latest/plugins/email.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 4a2ab36035..9fb0b94d16 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or external providers. 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 or using a lifecycle hook for admin panel use cases. +The Email plugin enables applications to send emails from a server or external providers. 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. ::: prerequisite @@ -15,16 +15,16 @@ The Email plugin requires a provider and a provider configuration in the `plugin ::: ::: note -[`Sendmail`](https://www.npmjs.com/package/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 provided configuration. For production stage applications you need to further configure `Sendmail` or change providers. The [Using providers documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, configuring providers, and creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, configuring providers, and creating a new email provider. ::: ## Sending emails -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. +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. Both functions utilize the email provider enabled in the `plugins.js` configuration file. ### Using the `send` function in the back end -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function utilizes the email provider enabled in the `plugins.js` configuration file. The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function can be used by extending a core controller/service or developing a custom controller/service. ```js @@ -76,15 +76,15 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -### Using a lifecycle hook +### Using `send ` 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](/developer-docs/latest/development/backend-customization/models.md#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 `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](#using-the-send-function-in-the-back-end), with the same available properties. - - Fields from the new content entry can be included in the email using the `text` property and the value `${fieldName}` to indicate which field should be included. +- 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](#using-the-send-function-in-the-back-end), with the same available properties. +- Fields from the new content entry can be included in the email using the `text` property and the value `${fieldName}` to indicate which field should be included. ```js @@ -99,7 +99,7 @@ module.exports = { to: 'a valid email address', from: 'a valid email address', subject: 'A new content entry', - text: '${welcomeMessage}' + text: '${fieldName}' }) } catch(err) { console.log(err); From c342e5894212255880de05ff3745fd85715ca79b Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 4 Jul 2022 14:52:52 +0200 Subject: [PATCH 45/74] simplify wording --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 9fb0b94d16..9b50b6d29a 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -24,7 +24,7 @@ The functions `send` and `sendTemplatedEmail` are available to send emails. The ### Using the `send` function in the back end -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The function can be used by extending a core controller/service or developing a custom controller/service. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). ```js From 53e2890b3f14776d7a74c906082bd34fc33df6d4 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 4 Jul 2022 17:30:24 +0200 Subject: [PATCH 46/74] fix code block file paths and header levels --- docs/developer-docs/latest/plugins/email.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 9b50b6d29a..e6e493755e 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -18,7 +18,7 @@ The Email plugin requires a provider and a provider configuration in the `plugin [`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, configuring providers, and creating a new email provider. ::: -## Sending emails +## 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. Both functions utilize the email provider enabled in the `plugins.js` configuration file. @@ -28,7 +28,8 @@ To trigger an email in response to a user action add the following function to a ```js -// e.g. path: ./src/api/{api name}/controllers/{api name}.js +// 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', @@ -54,7 +55,8 @@ The Email plugin provides the function `sendTemplatedEmail` to compose emails fr ```js -// e.g. path: ./src/api/{api name}/controllers/{api name}.js +// 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 %>', @@ -76,7 +78,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ); ``` -### Using `send ` with a lifecycle hook +## 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](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks). For example, an editor can receive an email each time an author creates a new content entry in the Content Manager. From 22c4c5d0afbe7c7ef258c52944a32d67a3e35aa3 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 5 Jul 2022 08:19:52 +0200 Subject: [PATCH 47/74] fixed various parts --- docs/developer-docs/latest/plugins/email.md | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index e6e493755e..c389756119 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,25 +6,25 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -The Email plugin enables applications to send emails from a server or external providers. 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. +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. -::: prerequisite +::: prerequisites -The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[ Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[ Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. ::: ::: note -[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers documentation](/developer-docs/latest/development/using-providers.md) has instructions for changing providers, configuring providers, and creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers ](/developer-docs/latest/development/using-providers.md)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. Both functions utilize the email provider enabled in the `plugins.js` configuration file. +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 in the back end +### Using the `send` function -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). 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. ```js @@ -43,9 +43,9 @@ To trigger an email in response to a user action add the following function to a }), ``` -### Using the `sendTemplatedEmail` function in the back end +### Using the `sendTemplatedEmail` function -The Email plugin provides 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. +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 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| @@ -82,11 +82,11 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( Another use case for the Email plugin is to trigger an email based on administrator actions in the admin panel using [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#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 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](#using-the-send-function-in-the-back-end), with the same available properties. -- Fields from the new content entry can be included in the email using the `text` property and the value `${fieldName}` to indicate which field should be included. +- 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. ```js From bc5825f1091d6445518987796ff496ecc9f39a1e Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 5 Jul 2022 10:14:03 +0200 Subject: [PATCH 48/74] update node engines --- docs/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/package.json b/docs/package.json index 97063beb54..427d104254 100644 --- a/docs/package.json +++ b/docs/package.json @@ -47,7 +47,7 @@ ], "license": "MIT", "engines": { - "node": ">=12.x.x <=16.x.x", + "node": "14.x.x", "npm": ">=6.0.0" } } From 1f43dbef2d835f5fd144e53d5b6e12187634f49c Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 5 Jul 2022 10:36:32 +0200 Subject: [PATCH 49/74] add spaces to empty object braces --- docs/developer-docs/latest/plugins/email.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index c389756119..91a050d028 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -49,9 +49,9 @@ The Email plugin includes the function `sendTemplatedEmail` to compose emails fr | 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](https://lodash.com/docs/4.17.15#template) | `object` | {} | -| `data` | Contains the data used to compile the templates | `object` | {} | +| `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](https://lodash.com/docs/4.17.15#template) | `object` | { } | +| `data` | Contains the data used to compile the templates | `object` | { } | ```js From 6bb3eb5a8a384b531fa67a2f479ceac7e7c70764 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 5 Jul 2022 17:42:48 +0200 Subject: [PATCH 50/74] trim content --- docs/developer-docs/latest/plugins/email.md | 35 ++++++++++----------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 91a050d028..8b1eae3f5e 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -20,11 +20,11 @@ The Email plugin requires a provider and a provider configuration in the `plugin ## 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. +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 +### Using the `send()` function -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). 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. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). 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. ```js @@ -43,9 +43,9 @@ To trigger an email in response to a user action add the following function to a }), ``` -### Using the `sendTemplatedEmail` function +### 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. +The `sendTemplatedEmail()` 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 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| @@ -80,28 +80,27 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ## 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](/developer-docs/latest/development/backend-customization/models.md#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](#using-the-send-function-in-the-back-end), 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. + To trigger an email based on administrator actions in the admin panel use [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#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: ```js -// e.g. path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js +// path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js module.exports = { - async afterCreate(event) { + async afterCreate(event) { // Connected to "Save" button in admin panel 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}' + 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); From edd8bfd6e25cdd650f0a0800d350a4dc70c727b5 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 5 Jul 2022 17:59:02 +0200 Subject: [PATCH 51/74] shorten send func disc --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 8b1eae3f5e..7c1ec41f92 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -24,7 +24,7 @@ The functions `send()` and `sendTemplatedEmail()` are available to send emails. ### Using the `send()` function -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). 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. +To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). ```js From 1f342f807ab20107a279799a98554d5842b46de4 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Thu, 7 Jul 2022 12:28:23 +0200 Subject: [PATCH 52/74] feedback updates --- docs/developer-docs/latest/plugins/upload.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index ab41a8a66d..52a614bcf6 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -6,9 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/upload.html # Upload -The `Upload` plugin is the backend powering the [Media Library](../../../user-docs/latest/media-library/introduction-to-media-library.md) plugin available by default in the Strapi admin panel. - -Using either the Media Library UI or the upload API directly, you can upload any kind of file for use in your Strapi application. +The Upload plugin is the backend powering the [Media Library](../../../user-docs/latest/media-library/introduction-to-media-library.md) plugin available by default in the Strapi admin panel. Using either the Media Library from the admin panel or the upload API directly, you can upload any kind of file for use in your Strapi application. By default Strapi provides a [provider](../development/using-providers.md) that uploads files to a local directory. Additional providers are available should you want to upload your files to another location. @@ -47,7 +45,7 @@ module.exports = ({ env })=>({ ### Max file size -Currently the Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of **200MB**. +Currently the Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 200MB. The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it uses the [`node-formidable`](https://github.com/felixge/node-formidable) library to process files. From fec3cb31b6f0a62be55634f01955308c70dc48c2 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 7 Jul 2022 15:05:23 +0200 Subject: [PATCH 53/74] add optional to table --- docs/developer-docs/latest/plugins/email.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 7c1ec41f92..40e3e4a531 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -47,11 +47,13 @@ To trigger an email in response to a user action add the following function to a The `sendTemplatedEmail()` 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` | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | +| `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](https://lodash.com/docs/4.17.15#template) | `object` | { } | -| `data` | Contains the data used to compile the templates | `object` | { } | +| `data` (optional) | Contains the data used to compile the templates | `object` | { } | ```js From b92ee454641c7df0ed581a54747b0b3efca64a58 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 7 Jul 2022 16:15:33 +0200 Subject: [PATCH 54/74] Add send function properties table --- docs/developer-docs/latest/plugins/email.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 40e3e4a531..3d8a0ef41d 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -26,6 +26,18 @@ The functions `send()` and `sendTemplatedEmail()` are available to send emails. To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). + +| Property | Type | Format | +|-----------|----------|---------------| +| `from` | `string` | email address | +| `to` | `string` | email address | +| `cc` | `string` | email address | +| `bcc` | `string` | email address | +| `replyTo` | `string` | email address | +| `subject` | `string` | | +| `text` | `string` | | +| `html` | `string` | HTML | + ```js // This code example can be used in a controller or a service From 872d4b800fa1ddc4a01c7c910f698763c2408318 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Thu, 7 Jul 2022 17:12:10 +0200 Subject: [PATCH 55/74] updated send function table --- docs/developer-docs/latest/plugins/email.md | 25 ++++++++++----------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 3d8a0ef41d..7f5215de73 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -24,19 +24,18 @@ The functions `send()` and `sendTemplatedEmail()` are available to send emails. ### Using the `send()` function -To trigger an email in response to a user action add the following function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). - - -| Property | Type | Format | -|-----------|----------|---------------| -| `from` | `string` | email address | -| `to` | `string` | email address | -| `cc` | `string` | email address | -| `bcc` | `string` | email address | -| `replyTo` | `string` | email address | -| `subject` | `string` | | -| `text` | `string` | | -| `html` | `string` | HTML | +To trigger an email in response to a user action add the `send()` function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The send function has the following properties: + +| Property | Type | Format | +|----------------------------------------------------------------------|----------|---------------| +| `from`

        If not specified, uses `defaultFrom` in `plugins.js`. | `string` | email address | +| `to`

        (Required) | `string` | email address | +| `cc` | `string` | email address | +| `bcc` | `string` | email address | +| `replyTo` | `string` | email address | +| `subject`

        (Required) | `string` | | +| `text`

        Either `text` or `html` is required. | `string` | | +| `html`

        Either `text` or `html` is required. | `string` | HTML | ```js From 323075218aab374259d14cdae7e87e83e4c24b76 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Fri, 8 Jul 2022 06:13:35 +0200 Subject: [PATCH 56/74] add spacing --- docs/developer-docs/latest/plugins/email.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 7f5215de73..e753c6aa4e 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -37,6 +37,12 @@ To trigger an email in response to a user action add the `send()` function to a | `text`

        Either `text` or `html` is required. | `string` | | | `html`

        Either `text` or `html` is required. | `string` | HTML | + + + + + + ```js // This code example can be used in a controller or a service @@ -56,15 +62,15 @@ To trigger an email in response to a user action add the `send()` function to a ### Using the `sendTemplatedEmail()` function -The `sendTemplatedEmail()` 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. +The `sendTemplatedEmail()` 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` | { } | +| `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](https://lodash.com/docs/4.17.15#template) | `object` | { } | -| `data` (optional) | Contains the data used to compile the templates | `object` | { } | +| `data`

        (optional) | Contains the data used to compile the templates | `object` | { } | ```js From 40da37423315076810dfec6b2de3901227c480a7 Mon Sep 17 00:00:00 2001 From: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> Date: Fri, 8 Jul 2022 08:16:40 +0200 Subject: [PATCH 57/74] Update docs/developer-docs/latest/plugins/email.md Co-authored-by: Pierre Wizla --- docs/developer-docs/latest/plugins/email.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index e753c6aa4e..165f6a6f1a 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -20,7 +20,9 @@ The Email plugin requires a provider and a provider configuration in the `plugin ## 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. +The Email plugin comes with an `email` [service](/developer-docs/latest/development/backend-customization/services.md#services) that includes/offers/provides 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 From 722c2997558875b08b871f36a3aa993f6ae345df Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Fri, 8 Jul 2022 08:42:50 +0200 Subject: [PATCH 58/74] updated minor wording + delint --- docs/developer-docs/latest/plugins/email.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 165f6a6f1a..c4f9976219 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,18 +10,19 @@ The Email plugin enables applications to send emails from a server or an externa ::: prerequisites -The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[ Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. ::: ::: note -[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers ](/developer-docs/latest/development/using-providers.md)documentation has instructions for changing providers, configuring providers, and creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers](/developer-docs/latest/development/using-providers.md)documentation has instructions for changing providers, configuring providers, and creating a new email provider. ::: ## Sending emails with a controller or service -The Email plugin comes with an `email` [service](/developer-docs/latest/development/backend-customization/services.md#services) that includes/offers/provides 2 functions to send emails: -* `send()` directly contains the email contents, +The Email plugin has an `email` [service](/developer-docs/latest/development/backend-customization/services.md#services) 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 @@ -39,12 +40,6 @@ To trigger an email in response to a user action add the `send()` function to a | `text`

        Either `text` or `html` is required. | `string` | | | `html`

        Either `text` or `html` is required. | `string` | HTML | - - - - - - ```js // This code example can be used in a controller or a service From db93e9bd5baad4bec41683b97ec3fe69e4f9fff2 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Fri, 8 Jul 2022 09:12:11 +0200 Subject: [PATCH 59/74] add space --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index c4f9976219..966936125f 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,7 +10,7 @@ The Email plugin enables applications to send emails from a server or an externa ::: prerequisites -The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the[Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. ::: @@ -96,7 +96,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ## Sending emails with a lifecycle hook - To trigger an email based on administrator actions in the admin panel use [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#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: + To trigger an email based on administrator actions in the admin panel use [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) and the [`send()` function](#using-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: ```js From a4f37f8a8106e5e783b6f0aa7868becd54162783 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 11 Jul 2022 09:48:47 +0200 Subject: [PATCH 60/74] feedback revisions --- docs/developer-docs/latest/development/using-providers.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index 4a642a1f77..c749d9c5dd 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -24,7 +24,7 @@ For example: - + ```sh # Install the AWS S3 provider for the Upload plugin npm install @strapi/provider-upload-aws-s3 --save @@ -80,7 +80,9 @@ module.exports = ({ env }) => ({ }); ``` -Strapi has a default `security` middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. +::: note +Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. +::: ::: From c6fb0af80f14a9e3af0404697100614cdce3da94 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 11 Jul 2022 11:01:53 +0200 Subject: [PATCH 61/74] modify `send` properties table --- docs/developer-docs/latest/plugins/email.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 966936125f..0a757bdc83 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -29,16 +29,16 @@ The Email plugin has an `email` [service](/developer-docs/latest/development/bac To trigger an email in response to a user action add the `send()` function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The send function has the following properties: -| Property | Type | Format | -|----------------------------------------------------------------------|----------|---------------| -| `from`

        If not specified, uses `defaultFrom` in `plugins.js`. | `string` | email address | -| `to`

        (Required) | `string` | email address | -| `cc` | `string` | email address | -| `bcc` | `string` | email address | -| `replyTo` | `string` | email address | -| `subject`

        (Required) | `string` | | -| `text`

        Either `text` or `html` is required. | `string` | | -| `html`

        Either `text` or `html` is required. | `string` | HTML | +| 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. | ```js @@ -65,9 +65,9 @@ The `sendTemplatedEmail()` is used to compose emails from a template. The functi | Parameter | Description | Type | Default | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| -| `emailOptions`

        (optional) | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | +| `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](https://lodash.com/docs/4.17.15#template) | `object` | { } | -| `data`

        (optional) | Contains the data used to compile the templates | `object` | { } | +| `data`

        Optional | Contains the data used to compile the templates | `object` | { } | ```js From 99a7fba91349bcb9a37ebedef84476592afa305f Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 11 Jul 2022 12:30:57 +0200 Subject: [PATCH 62/74] feedback --- docs/developer-docs/latest/plugins/upload.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 52a614bcf6..37d928294f 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -25,7 +25,7 @@ This section details configuration options for the default upload provider. If u By default Strapi accepts `localServer` configurations for locally uploaded files. These will be passed as the options for [koa-static](https://github.com/koajs/static). -You can provide them by creating or editing the `./config/plugins.js` file. The example below sets the `max-age` header. +You can provide them by creating or editing the `./config/plugins.js` file. The following example sets the `max-age` header. ```js // path: ./config/plugins.js @@ -49,7 +49,7 @@ Currently the Strapi middleware in charge of parsing requests needs to be config The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it uses the [`node-formidable`](https://github.com/felixge/node-formidable) library to process files. -You can pass configuration to the middleware directly by setting it in the `body` middleware configuration in `./config/middlewares.js`: +You can pass configuration to the middleware directly by setting it in the [`body` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#internal-middlewares-configuration-reference) configuration in `./config/middlewares.js`: ```js // path: ./config/middlewares.js From b47cbe36aff3c05f95cedcca08a88bf75c27f304 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 11 Jul 2022 12:40:43 +0200 Subject: [PATCH 63/74] feedback --- docs/developer-docs/latest/plugins/sentry.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md index 0db8a123af..07c26319f0 100644 --- a/docs/developer-docs/latest/plugins/sentry.md +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -15,6 +15,8 @@ By using the Sentry plugin you can: * Include additional metadata in Sentry events to assist in debugging * Expose a [global Sentry service](#global-sentry-service) +Begin by first [installing](#installation) the Sentry plugin, and then [configuring](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. + ## Installation Install the Sentry plugin by adding the dependency to your Strapi application as follows: @@ -35,8 +37,6 @@ yarn add @strapi/plugin-sentry         -Then you must [configure](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. - ## Configuration Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: @@ -96,7 +96,7 @@ This service exposes the following methods: | `sendError` | Manually send errors to Sentry. |
        • error: The error to be sent.
        • configureScope: Optional. Enables you to customize the error event.

        See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | | `getInstance` | Used for direct access to the Sentry instance. | | -### Examples +Below are examples for each method. :::: tabs card From f1e3658e6b1dcfbb30fd2626b090de6e4b4e4b44 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 11 Jul 2022 12:49:44 +0200 Subject: [PATCH 64/74] revisions --- docs/developer-docs/latest/plugins/sentry.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md index 07c26319f0..5855c09d8e 100644 --- a/docs/developer-docs/latest/plugins/sentry.md +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -67,7 +67,7 @@ module.exports = ({ env }) => ({ ### Environment configuration -Using the `env` utility, you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: +Using the [`env` utility](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md#configuration-using-environment-variables), you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: ```js // path: ./config/plugins.js @@ -81,7 +81,7 @@ module.exports = ({ env }) => ({ }); ``` -## Global Sentry service +## Global Sentry service access After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows: @@ -93,8 +93,8 @@ This service exposes the following methods: | Method | Description | Parameters | | ------ | ----------- | ---------- | -| `sendError` | Manually send errors to Sentry. |
        • error: The error to be sent.
        • configureScope: Optional. Enables you to customize the error event.

        See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | -| `getInstance` | Used for direct access to the Sentry instance. | | +| `sendError()` | Manually send errors to Sentry. |
        • error: The error to be sent.
        • configureScope: Optional. Enables you to customize the error event.

        See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | +| `getInstance()` | Used for direct access to the Sentry instance. | | Below are examples for each method. From 8f2c7b575a56cb7313310f96686695ff678b5047 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 11 Jul 2022 13:14:32 +0200 Subject: [PATCH 65/74] fix links in admin panel config file --- .../configurations/required/admin-panel.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md index 99e38a5405..5394f02c27 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md @@ -29,9 +29,9 @@ The `./config/admin.js` file can include the following parameters: | `port` | Use a different port for the admin panel. Only used along with `strapi develop --watch-admin` | string | `8000` | | `serveAdminPanel` | If false, the admin panel won't be served. Note: the `index.html` will still be served, see [defaultIndex option](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md) | boolean | `true` | | `forgotPassword` | Settings to customize the forgot password email (see more here: [Forgot Password Email](/developer-docs/latest/development/admin-customization.md#forgotten-password-email)) | object | {} | -| `forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#programmatic-usage) | object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | -| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | -| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | +| `forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#using-the-sendtemplatedemail-function) | object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | +| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/development/using-providers.md#configuring-providers) | +| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/development/using-providers.md#configuring-providers) | ## Configurations From 9a05da43a44ba0770b687f7d3fc4bd5c99691f2e Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 11 Jul 2022 13:20:04 +0200 Subject: [PATCH 66/74] delint --- docs/developer-docs/latest/plugins/email.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 0a757bdc83..a7f9fecc9b 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,7 +10,7 @@ The Email plugin enables applications to send emails from a server or an externa ::: prerequisites -The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. ::: @@ -61,8 +61,6 @@ To trigger an email in response to a user action add the `send()` function to a The `sendTemplatedEmail()` 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` | { } | From 4767b19a1321a09c5531bf40b17d2b7a13d39d24 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 12 Jul 2022 10:44:05 +0200 Subject: [PATCH 67/74] minor fixes --- docs/developer-docs/latest/development/using-providers.md | 3 --- docs/developer-docs/latest/plugins/email.md | 2 +- docs/developer-docs/latest/plugins/sentry.md | 2 +- 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index c749d9c5dd..465cae5919 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -84,8 +84,6 @@ module.exports = ({ env }) => ({ Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. ::: -::: - ::: tab Email ```js @@ -155,7 +153,6 @@ module.exports = { }, }; ``` -::: ::: tab Email diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index a7f9fecc9b..d0e7ceb7d4 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -15,7 +15,7 @@ The Email plugin requires a provider and a provider configuration in the `plugin ::: ::: note -[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers](/developer-docs/latest/development/using-providers.md)documentation has instructions for changing providers, configuring providers, and creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers](/developer-docs/latest/development/using-providers.md) documentation has instructions for changing providers, configuring providers, and creating a new email provider. ::: ## Sending emails with a controller or service diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md index 5855c09d8e..5949d933e3 100644 --- a/docs/developer-docs/latest/plugins/sentry.md +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -13,7 +13,7 @@ By using the Sentry plugin you can: * Initialize a Sentry instance upon startup of a Strapi application * Send Strapi application errors as events to Sentry * Include additional metadata in Sentry events to assist in debugging -* Expose a [global Sentry service](#global-sentry-service) +* Expose a [global Sentry service](#global-sentry-service-access) Begin by first [installing](#installation) the Sentry plugin, and then [configuring](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. From 80aae6477e47954983f9e0401c8751732751af44 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:05:37 +0200 Subject: [PATCH 68/74] Update docs/developer-docs/latest/development/using-providers.md Co-authored-by: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> --- docs/developer-docs/latest/development/using-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index 465cae5919..3f19ada165 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -153,7 +153,7 @@ module.exports = { }, }; ``` - +::: ::: tab Email ```js From f09fdfdef2f49a4651d2c51a938b3bc20ee27504 Mon Sep 17 00:00:00 2001 From: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:50:48 +0200 Subject: [PATCH 69/74] Update docs/developer-docs/latest/plugins/email.md Co-authored-by: Pierre Wizla --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index d0e7ceb7d4..51553b9b1c 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -94,7 +94,7 @@ await strapi.plugins['email'].services.email.sendTemplatedEmail( ## Sending emails with a lifecycle hook - To trigger an email based on administrator actions in the admin panel use [Lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) and the [`send()` function](#using-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: + To trigger an email based on administrator actions in the admin panel use [lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) and the [`send()` function](#using-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: ```js From 551137ca261dfd7d5fe5e0b63070b62680c79bd0 Mon Sep 17 00:00:00 2001 From: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:51:11 +0200 Subject: [PATCH 70/74] Update docs/developer-docs/latest/plugins/email.md --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 51553b9b1c..1818409867 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -59,7 +59,7 @@ To trigger an email in response to a user action add the `send()` function to a ### Using the `sendTemplatedEmail()` function -The `sendTemplatedEmail()` 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: +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 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| From c820b22984a0f0cc23b8a80b5845eeab97ab9ddc Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:54:48 +0200 Subject: [PATCH 71/74] Feedback --- docs/.vuepress/config/sidebar-developer.js | 2 +- .../development/{using-providers.md => providers.md} | 8 ++++---- docs/developer-docs/latest/plugins/upload.md | 4 ++-- .../configurations/required/admin-panel.md | 4 ++-- .../deployment/hosting-guides/amazon-aws.md | 2 +- .../deployment/hosting-guides/azure.md | 2 +- .../deployment/hosting-guides/heroku.md | 2 +- docs/user-docs/latest/plugins/introduction-to-plugins.md | 4 ++-- 8 files changed, 14 insertions(+), 14 deletions(-) rename docs/developer-docs/latest/development/{using-providers.md => providers.md} (93%) diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 7e4ed347b2..2546cdb018 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -222,7 +222,7 @@ const developer = [ ['/developer-docs/latest/development/admin-customization', 'Admin panel customization'], ['/developer-docs/latest/development/plugins-extension.md', 'Plugins extension'], ['/developer-docs/latest/development/plugins-development.md', 'Plugins development'], - ['/developer-docs/latest/development/using-providers.md', 'Using providers'], + ['/developer-docs/latest/development/providers.md', 'Providers'], ], }, { diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/providers.md similarity index 93% rename from docs/developer-docs/latest/development/using-providers.md rename to docs/developer-docs/latest/development/providers.md index 3f19ada165..19f6ec8517 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/providers.md @@ -1,10 +1,10 @@ --- -title: Using Providers - Strapi Developer Docs +title: Providers - Strapi Developer Docs description: Install and use providers to extend the functionality of available plugins. -canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/using-providers.html +canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/providers.html --- -# Using Providers +# Providers Certain [plugins](../../../user-docs/latest/plugins/introduction-to-plugins.md) can be extended via the installation and configuration of additional [providers](../../../user-docs/latest/plugins/introduction-to-plugins.md#providers). @@ -81,7 +81,7 @@ module.exports = ({ env }) => ({ ``` ::: note -Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. +Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#security) that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#security) for more information. ::: ::: tab Email diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 37d928294f..d809660753 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -6,9 +6,9 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/upload.html # Upload -The Upload plugin is the backend powering the [Media Library](../../../user-docs/latest/media-library/introduction-to-media-library.md) plugin available by default in the Strapi admin panel. Using either the Media Library from the admin panel or the upload API directly, you can upload any kind of file for use in your Strapi application. +The Upload plugin is the backend powering the Media Library plugin available by default in the Strapi admin panel. Using either the Media Library from the admin panel or the upload API directly, you can upload any kind of file for use in your Strapi application. -By default Strapi provides a [provider](../development/using-providers.md) that uploads files to a local directory. Additional providers are available should you want to upload your files to another location. +By default Strapi provides a [provider](../development/providers.md) that uploads files to a local directory. Additional providers are available should you want to upload your files to another location. The providers maintained by Strapi include: diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md index 5394f02c27..1b1d229f19 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md @@ -30,8 +30,8 @@ The `./config/admin.js` file can include the following parameters: | `serveAdminPanel` | If false, the admin panel won't be served. Note: the `index.html` will still be served, see [defaultIndex option](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md) | boolean | `true` | | `forgotPassword` | Settings to customize the forgot password email (see more here: [Forgot Password Email](/developer-docs/latest/development/admin-customization.md#forgotten-password-email)) | object | {} | | `forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#using-the-sendtemplatedemail-function) | object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | -| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/development/using-providers.md#configuring-providers) | -| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/development/using-providers.md#configuring-providers) | +| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/development/providers.md#configuring-providers) | +| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/development/providers.md#configuring-providers) | ## Configurations diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md index a13aea9bc0..63a169011b 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md @@ -362,7 +362,7 @@ module.exports = ({ env }) => ({ }); ``` -Checkout the documentation about using an upload provider [here](/developer-docs/latest/plugins/upload.md#using-a-provider). +Checkout the documentation about using an upload provider [here](/developer-docs/latest/development/providers.md). #### 4. Push your local changes to your project's GitHub repository. diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md index 497dbad6fe..6ef12e727a 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md @@ -662,4 +662,4 @@ There are many different types of proxy services you could use, anything from lo #### 3. File upload providers -There are many options for storing files outside of your virtual machine, Strapi have built a few and the community is constantly building new ones. See the [following guide](/developer-docs/latest/plugins/upload.md#create-providers) on searching for options as well as installing them. +There are many options for storing files outside of your virtual machine, Strapi have built a few and the community is constantly building new ones. See the [following guide](/developer-docs/latest/development/providers.md) on searching for options as well as installing them. diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md index e849aa6e98..55286efa60 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md @@ -363,7 +363,7 @@ heroku open Like with project updates on Heroku, the file system doesn't support local uploading of files as they will be wiped when Heroku "cycles" the dyno. This type of file system is called [ephemeral](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem), which means the file system only lasts until the dyno is restarted (with Heroku this happens any time you redeploy or during their regular restart which can happen every few hours or every day). -Due to Heroku's filesystem you will need to use an upload provider such as AWS S3, Cloudinary, or Rackspace. You can view the documentation for installing providers [here](/developer-docs/latest/plugins/upload.md#create-providers) and you can see a list of providers from both Strapi and the community on [npmjs.com](https://www.npmjs.com/search?q=strapi-provider-upload-&page=0&perPage=20). +Due to Heroku's filesystem you will need to use an upload provider such as AWS S3, Cloudinary, or Rackspace. You can view the documentation for installing providers [here](/developer-docs/latest/development/providers.md) and you can see a list of providers from both Strapi and the community on [npmjs.com](https://www.npmjs.com/search?q=strapi-provider-upload-&page=0&perPage=20). ## Gzip diff --git a/docs/user-docs/latest/plugins/introduction-to-plugins.md b/docs/user-docs/latest/plugins/introduction-to-plugins.md index 41c33fbbeb..e5a34ce22f 100644 --- a/docs/user-docs/latest/plugins/introduction-to-plugins.md +++ b/docs/user-docs/latest/plugins/introduction-to-plugins.md @@ -32,5 +32,5 @@ Some plugins can be further extended through the configuration of _providers_, p Currently, the only plugins designed to work with providers are the: -* [Email plugin](../../../developer-docs/latest/plugins/email.md#configure-the-plugin), and -* [Media Library plugin](../../../developer-docs/latest/plugins/upload.md#using-a-provider) (implemented via the [Upload plugin](../../../developer-docs/latest/plugins/upload.md)). +* [Email plugin](/developer-docs/latest/plugins/email.md), and +* Media Library plugin (implemented via the [Upload plugin](/developer-docs/latest/plugins/upload.md)). From 5cd4701a7fb4546e3f1cff28d879ab49b5f04ba9 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:55:52 +0200 Subject: [PATCH 72/74] title fix --- docs/developer-docs/latest/plugins/email.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 1818409867..0902323495 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -10,12 +10,12 @@ The Email plugin enables applications to send emails from a server or an externa ::: prerequisites -The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Using providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Providers](/developer-docs/latest/development/using-providers.md) documentation for detailed installation and configuration instructions. ::: ::: note -[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Using providers](/developer-docs/latest/development/using-providers.md) documentation has instructions for changing providers, configuring providers, and creating a new email provider. +[`Sendmail`](https://www.npmjs.com/package/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` or change providers. The [Providers](/developer-docs/latest/development/using-providers.md) documentation has instructions for changing providers, configuring providers, and creating a new email provider. ::: ## Sending emails with a controller or service From af525a5bb5d7fe0d9d3e96bf04e7cb8f5bda85e0 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 12 Jul 2022 16:59:40 +0200 Subject: [PATCH 73/74] add table --- docs/developer-docs/latest/plugins/upload.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index d809660753..5722342c84 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -49,7 +49,7 @@ Currently the Strapi middleware in charge of parsing requests needs to be config The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it uses the [`node-formidable`](https://github.com/felixge/node-formidable) library to process files. -You can pass configuration to the middleware directly by setting it in the [`body` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#internal-middlewares-configuration-reference) configuration in `./config/middlewares.js`: +You can pass configuration to the middleware directly by setting it in the [`body` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#body) configuration in `./config/middlewares.js`: ```js // path: ./config/middlewares.js @@ -209,12 +209,14 @@ Upload one or more files that will be linked to a specific entry. The following parameters are accepted: -- `files`: The file(s) to upload. The value(s) can be a Buffer or Stream. -- `path` (optional): The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). -- `refId`: The ID of the entry which the file(s) will be linked to. -- `ref`: The unique ID (uid) of the model which the file(s) will be linked to (see more below). -- `source` (optional): The name of the plugin where the model is located. -- `field`: The field of the entry which the file(s) will be precisely linked to. +| Parameter | Description | +| --------- | ----------- | +|`files` | The file(s) to upload. The value(s) can be a Buffer or Stream. | +|`path` (optional) | The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). | +| `refId` | The ID of the entry which the file(s) will be linked to. | +| `ref` | The unique ID (uid) of the model which the file(s) will be linked to (see more below). | +| `source` (optional) | The name of the plugin where the model is located. | +| `field` | The field of the entry which the file(s) will be precisely linked to. | For example, given the `Restaurant` model attributes: From 090f4bc9a2e02a39803a56c7262a11cf5629e621 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Wed, 13 Jul 2022 09:55:38 +0200 Subject: [PATCH 74/74] Add Sentry to PluginLinks component --- .../theme/global-components/PluginsLinks.vue | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/.vuepress/theme/global-components/PluginsLinks.vue b/docs/.vuepress/theme/global-components/PluginsLinks.vue index 0ea10d7a8f..dd869ce40f 100644 --- a/docs/.vuepress/theme/global-components/PluginsLinks.vue +++ b/docs/.vuepress/theme/global-components/PluginsLinks.vue @@ -261,6 +261,19 @@ + + +
        + + + + + +