From 7f6a31f08c907904214f02ba113541e05f0b83be Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 6 Mar 2023 01:42:29 +0000 Subject: [PATCH 01/12] first draft --- 022-custom-smtp-and-email-templates.md | 139 +++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 022-custom-smtp-and-email-templates.md diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md new file mode 100644 index 0000000..ab0e41a --- /dev/null +++ b/022-custom-smtp-and-email-templates.md @@ -0,0 +1,139 @@ +# Custom SMTP and Email/SMS Templates Support + +- Implementation Owner: @lohanidamodar +- Start Date: 2023-03-06 +- Target Date: 2023-03-18 +- Appwrite Issue: [https://github.com/appwrite/appwrite/issues/4664](https://github.com/appwrite/appwrite/issues/4664) + +## Summary + +[summary]: #summary + +Support custom SMTP configuration per project and support customizing the email and sms templates. This allows users to set project specific templates as required by the project. Custom email templates will only be supported if the custom SMTP is enabled. + +## Problem Statement (Step 1) + +[problem-statement]: #problem-statement + +**What problem are you trying to solve?** + +Right now the whole Appwrite system uses a single global SMTP configuration set via environment variables, this means all the projects will use the same email configuration. As well there is no way for user to customize the default email templates. As Appwrite supports multiple projects, which may have different needs for emailing. It is even more crucial in the cloud to support custom email templating as each individual users will have their own need for the project and may want to use their own emailing system to send emails. + +## Design proposal (Step 2) + +[design-proposal]: #design-proposal + +### API Endpoints + +For this we will introduce various endpoints + +**PATCH /v1/project/:projectId/smtp** - an endpoint for updating smtp configuration for the project + +It will accept following parameters + +- **enabled** - boolean - **required** - whether or not the SMTP configuration is enabled +- **host** - string - SMTP server host name address +- **port** - string - SMTP server tcp port +- **secure** - string - SMTP secure protocol (empty or `tls`) +- **username** - string - SMTP server user name +- **password** - string - SMTP server password + +**PATCH /v1/project/:projectId/template** - an endpoint to update custom templates (email/sms) + +- **locale** - string - required (eg: en_us) - locale of the template +- **key** - string - template key (email.emailVerification, sms.pincode) - the key that defines what the template is for +- **template** - json encoded string - template content, that may have `subject`, `body`, `title`, `senderName`, `senderEmail`. + +### Data Structure + +Project document will be updated with new attributes to support SMTP and templates configuration + +- **smtp**: json - save SMTP configuration for the project will have following fields + - **enabled** - boolean - whether or not the SMTP configuration is enabled + - **host** - SMTP server host name address + - **port** - SMTP server tcp port + - **secure** - SMTP secure protocol (empty or `tls`) + - **username** - SMTP server user name + - **password** - SMTP server password + +- **templates**: json - save custom templates + - **key** - string - key that defines what the template is for + - **message** - string - template body (SMS templates will only have message) + - **locale** - string - template locale + - **subject** - string - subject, if email template + - **senderName** - string - sender name + - **senderEmail** - string - email of the sender + - **replyTo** - string - email reply to + + +### UI + +We will need new section under Authentication called **Email & SMS** where user will be able to add these template and SMTP configuration + +### Supporting Libraries + +We don't need any additional libraries to support this, we already have everything in place. + +### Breaking Changes + +This is a new feature and shouldn't break any existing features + +### Reliability (Tests & Benchmarks) + +#### Scaling + +This being the part of project API, scaling should already be taken care of. + +#### Benchmarks + +We don't need separate benchmark for this. + +#### Tests (UI, Unit, E2E) + +- New e2e tests will be added for these new configurations. +- UI tests will be written for newly added UI section + +### Documentation & Content + +- SMTP setup documentation should be updated to reflect project level configuration support +- New documentation regarding custom email and sms tempates should be added + +### Prior art + +[prior-art]: #prior-art + + + +N/A + +### Unresolved questions + +[unresolved-questions]: #unresolved-questions + + + + + +N/A + +### Future possibilities + +[future-possibilities]: #future-possibilities + + + + From 0be6716e359cf4f7f1b9e5bb03dd65f7b6350c18 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 6 Mar 2023 01:45:46 +0000 Subject: [PATCH 02/12] update --- 022-custom-smtp-and-email-templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index ab0e41a..ccd43cb 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -32,6 +32,7 @@ For this we will introduce various endpoints It will accept following parameters - **enabled** - boolean - **required** - whether or not the SMTP configuration is enabled +- **sender** - string - SMTP sender email - **host** - string - SMTP server host name address - **port** - string - SMTP server tcp port - **secure** - string - SMTP secure protocol (empty or `tls`) @@ -50,6 +51,7 @@ Project document will be updated with new attributes to support SMTP and templat - **smtp**: json - save SMTP configuration for the project will have following fields - **enabled** - boolean - whether or not the SMTP configuration is enabled + - **sender** - email of the sender - **host** - SMTP server host name address - **port** - SMTP server tcp port - **secure** - SMTP secure protocol (empty or `tls`) From b2b9e3a8ae23cd2511d36f883b26adb3152d8842 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Mon, 6 Mar 2023 01:49:13 +0000 Subject: [PATCH 03/12] update --- 022-custom-smtp-and-email-templates.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index ccd43cb..d86cb5d 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -45,6 +45,12 @@ It will accept following parameters - **key** - string - template key (email.emailVerification, sms.pincode) - the key that defines what the template is for - **template** - json encoded string - template content, that may have `subject`, `body`, `title`, `senderName`, `senderEmail`. +**GET /v1/project/:projectId/template** - endpoint to get existing templates. accepts following parameters +- **key** - string - key to identify the template +- **locale** - string - locale of the template + +If custom template doesn't exist for the given details, the default server template will be returned. + ### Data Structure Project document will be updated with new attributes to support SMTP and templates configuration From c20625a0836387c7d4477927c4d0776969e52e5f Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 7 Mar 2023 01:36:45 +0000 Subject: [PATCH 04/12] review updates --- 022-custom-smtp-and-email-templates.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index d86cb5d..495868b 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -45,12 +45,15 @@ It will accept following parameters - **key** - string - template key (email.emailVerification, sms.pincode) - the key that defines what the template is for - **template** - json encoded string - template content, that may have `subject`, `body`, `title`, `senderName`, `senderEmail`. -**GET /v1/project/:projectId/template** - endpoint to get existing templates. accepts following parameters +**GET /v1/project/:projectId/template/:type/:locale** - endpoint to get existing templates. accepts following parameters - **key** - string - key to identify the template - **locale** - string - locale of the template If custom template doesn't exist for the given details, the default server template will be returned. +**DELETE /v1/project/:projectId/template/:type/:locale** - endpoint to remove custom template +- Remove matching custom template or throw 404 if the custom template doesn't exist + ### Data Structure Project document will be updated with new attributes to support SMTP and templates configuration @@ -136,7 +139,7 @@ N/A -N/A +- Data structure for Template variables ### Future possibilities From e918de53141e0ceda3c39c888caec614535827b8 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 7 Mar 2023 01:39:47 +0000 Subject: [PATCH 05/12] updates --- 022-custom-smtp-and-email-templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index 495868b..b106c56 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -46,7 +46,7 @@ It will accept following parameters - **template** - json encoded string - template content, that may have `subject`, `body`, `title`, `senderName`, `senderEmail`. **GET /v1/project/:projectId/template/:type/:locale** - endpoint to get existing templates. accepts following parameters -- **key** - string - key to identify the template +- **type** - string - type to identify the template - **locale** - string - locale of the template If custom template doesn't exist for the given details, the default server template will be returned. @@ -68,7 +68,7 @@ Project document will be updated with new attributes to support SMTP and templat - **password** - SMTP server password - **templates**: json - save custom templates - - **key** - string - key that defines what the template is for + - **key** - string - key that defines what the template is for, it wil be ({type}-{locale} eg `sms.verification-en_us`, `email.resetPassword-en_us`) - **message** - string - template body (SMS templates will only have message) - **locale** - string - template locale - **subject** - string - subject, if email template From b61d1356d43ddd1d793bcfbb70d197890c409917 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 7 Mar 2023 01:55:17 +0000 Subject: [PATCH 06/12] updates --- 022-custom-smtp-and-email-templates.md | 81 ++++++++++++++++---------- 1 file changed, 50 insertions(+), 31 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index b106c56..3f21214 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -27,55 +27,74 @@ Right now the whole Appwrite system uses a single global SMTP configuration set For this we will introduce various endpoints -**PATCH /v1/project/:projectId/smtp** - an endpoint for updating smtp configuration for the project +**PATCH /v1/project/:projectId/smtp** - updates smtp configuration for the project It will accept following parameters -- **enabled** - boolean - **required** - whether or not the SMTP configuration is enabled -- **sender** - string - SMTP sender email -- **host** - string - SMTP server host name address -- **port** - string - SMTP server tcp port -- **secure** - string - SMTP secure protocol (empty or `tls`) -- **username** - string - SMTP server user name -- **password** - string - SMTP server password +- **enabled** : boolean - **required** - whether or not the SMTP configuration is enabled +- **sender** : string - SMTP sender email +- **host** : string - SMTP server host name address +- **port** : string - SMTP server tcp port +- **secure** : string - SMTP secure protocol (empty or `tls`) +- **username** : string - SMTP server user name +- **password** : string - SMTP server password -**PATCH /v1/project/:projectId/template** - an endpoint to update custom templates (email/sms) +**PATCH /v1/project/:projectId/template/sms/:type/:locale** - updates custom SMS templates -- **locale** - string - required (eg: en_us) - locale of the template -- **key** - string - template key (email.emailVerification, sms.pincode) - the key that defines what the template is for -- **template** - json encoded string - template content, that may have `subject`, `body`, `title`, `senderName`, `senderEmail`. +- **type** : string - required - template type +- **locale** : string - required (eg: en_us) - locale of the template +- **message** : string - template body -**GET /v1/project/:projectId/template/:type/:locale** - endpoint to get existing templates. accepts following parameters -- **type** - string - type to identify the template -- **locale** - string - locale of the template +**PATCH /v1/project/:projectId/template/email/:type/:locale** - updates custom email templates + +- **type** : string - required - template type +- **locale** : string - required (eg: en_us) - locale of the template +- **senderName** : string - required - name of the sender +- **senderEmail** : string - email of the sender +- **replyTo** : string - reply to email address +- **subject** : string - email subject +- **message** : string - email message body + +**GET /v1/project/:projectId/template/:type/:locale** - returns existing template + +- **type** : string - type to identify the template +- **locale** : string - locale of the template If custom template doesn't exist for the given details, the default server template will be returned. **DELETE /v1/project/:projectId/template/:type/:locale** - endpoint to remove custom template - Remove matching custom template or throw 404 if the custom template doesn't exist +**GET /v1/project/:projectId/template/:type/variables** - returns the list of supported template variables + ### Data Structure Project document will be updated with new attributes to support SMTP and templates configuration - **smtp**: json - save SMTP configuration for the project will have following fields - - **enabled** - boolean - whether or not the SMTP configuration is enabled - - **sender** - email of the sender - - **host** - SMTP server host name address - - **port** - SMTP server tcp port - - **secure** - SMTP secure protocol (empty or `tls`) - - **username** - SMTP server user name - - **password** - SMTP server password - -- **templates**: json - save custom templates + - **enabled** : boolean - whether or not the SMTP configuration is enabled + - **sender** : string - email of the sender + - **host** : string - SMTP server host name address + - **port** : string - SMTP server tcp port + - **secure** : string - SMTP secure protocol (empty or `tls`) + - **username** : string - SMTP server user name + - **password** : string - SMTP server password + +- **templates**: json - save custom templates (both SMS and email) - **key** - string - key that defines what the template is for, it wil be ({type}-{locale} eg `sms.verification-en_us`, `email.resetPassword-en_us`) - - **message** - string - template body (SMS templates will only have message) - - **locale** - string - template locale - - **subject** - string - subject, if email template - - **senderName** - string - sender name - - **senderEmail** - string - email of the sender - - **replyTo** - string - email reply to + - **message** : string - template body (SMS templates will only have message) + - **locale** : string - template locale + - **subject** : string - subject, if email template + - **senderName** : string - sender name + - **senderEmail** : string - email of the sender + - **replyTo** : string - email reply to + +New configuration for supported template variables. +- **templateVariables** : array + - **type** : array - template type + - **name** : string - name of the variable + - **description** : string - description of the variable ### UI @@ -139,7 +158,7 @@ N/A -- Data structure for Template variables +N/A ### Future possibilities From 361a33610563afcc7048c1572f4187796846a721 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 7 Mar 2023 01:58:28 +0000 Subject: [PATCH 07/12] update --- 022-custom-smtp-and-email-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index 3f21214..26407a3 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -62,7 +62,7 @@ It will accept following parameters If custom template doesn't exist for the given details, the default server template will be returned. -**DELETE /v1/project/:projectId/template/:type/:locale** - endpoint to remove custom template +**DELETE /v1/project/:projectId/template/:type/:locale** - removes custom template - Remove matching custom template or throw 404 if the custom template doesn't exist **GET /v1/project/:projectId/template/:type/variables** - returns the list of supported template variables From a5259136b0a47c4df8d97daa6b9aab9de61ba9f2 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 7 Mar 2023 02:29:40 +0000 Subject: [PATCH 08/12] query --- 022-custom-smtp-and-email-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index 26407a3..8b5cd42 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -158,7 +158,7 @@ N/A -N/A +- May be we should also have another configuration with list of all supported template types and endpoint to retrieve them? ### Future possibilities From b8bfb9c92eb4071f46db1eecbe6207cca31670c3 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Thu, 9 Mar 2023 06:55:36 +0545 Subject: [PATCH 09/12] update --- 022-custom-smtp-and-email-templates.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index 8b5cd42..c87be83 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -65,8 +65,6 @@ If custom template doesn't exist for the given details, the default server templ **DELETE /v1/project/:projectId/template/:type/:locale** - removes custom template - Remove matching custom template or throw 404 if the custom template doesn't exist -**GET /v1/project/:projectId/template/:type/variables** - returns the list of supported template variables - ### Data Structure Project document will be updated with new attributes to support SMTP and templates configuration @@ -99,6 +97,7 @@ New configuration for supported template variables. ### UI We will need new section under Authentication called **Email & SMS** where user will be able to add these template and SMTP configuration +UI should also include the documentation for supported template variables for each template. ### Supporting Libraries @@ -126,7 +125,7 @@ We don't need separate benchmark for this. ### Documentation & Content - SMTP setup documentation should be updated to reflect project level configuration support -- New documentation regarding custom email and sms tempates should be added +- New documentation regarding custom email and sms tempates should be added. ### Prior art From 1a5f148db1abc20baa349968233fdcc4ee555c17 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Thu, 9 Mar 2023 12:46:01 +0000 Subject: [PATCH 10/12] updates --- 022-custom-smtp-and-email-templates.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index c87be83..880d815 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -87,10 +87,10 @@ Project document will be updated with new attributes to support SMTP and templat - **senderEmail** : string - email of the sender - **replyTo** : string - email reply to -New configuration for supported template variables. +Console Project should include constants regarding supported templates and template variables -- **templateVariables** : array - - **type** : array - template type +- **templateVariables** : object + - **type** : object - template type (email.verification, email.reset, sms.verification) - **name** : string - name of the variable - **description** : string - description of the variable @@ -157,7 +157,6 @@ N/A -- May be we should also have another configuration with list of all supported template types and endpoint to retrieve them? ### Future possibilities From 925b8463aef01e9701b64e8649819eec31b98969 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Thu, 9 Mar 2023 18:55:48 +0545 Subject: [PATCH 11/12] updates --- 022-custom-smtp-and-email-templates.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index 880d815..dbb92b8 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -27,7 +27,7 @@ Right now the whole Appwrite system uses a single global SMTP configuration set For this we will introduce various endpoints -**PATCH /v1/project/:projectId/smtp** - updates smtp configuration for the project +**PATCH /v1/projects/:projectId/smtp** - updates smtp configuration for the project It will accept following parameters @@ -39,13 +39,13 @@ It will accept following parameters - **username** : string - SMTP server user name - **password** : string - SMTP server password -**PATCH /v1/project/:projectId/template/sms/:type/:locale** - updates custom SMS templates +**PATCH /v1/projects/:projectId/template/sms/:type/:locale** - updates custom SMS templates - **type** : string - required - template type - **locale** : string - required (eg: en_us) - locale of the template - **message** : string - template body -**PATCH /v1/project/:projectId/template/email/:type/:locale** - updates custom email templates +**PATCH /v1/projects/:projectId/template/email/:type/:locale** - updates custom email templates - **type** : string - required - template type - **locale** : string - required (eg: en_us) - locale of the template @@ -55,14 +55,14 @@ It will accept following parameters - **subject** : string - email subject - **message** : string - email message body -**GET /v1/project/:projectId/template/:type/:locale** - returns existing template +**GET /v1/projects/:projectId/template/:type/:locale** - returns existing template - **type** : string - type to identify the template - **locale** : string - locale of the template If custom template doesn't exist for the given details, the default server template will be returned. -**DELETE /v1/project/:projectId/template/:type/:locale** - removes custom template +**DELETE /v1/project/:projectId/templates/:type/:locale** - removes custom template - Remove matching custom template or throw 404 if the custom template doesn't exist ### Data Structure From 19dff3cb216217758bfd06a8dbf1b5072b480a92 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Thu, 20 Jul 2023 04:28:12 +0000 Subject: [PATCH 12/12] update --- 022-custom-smtp-and-email-templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/022-custom-smtp-and-email-templates.md b/022-custom-smtp-and-email-templates.md index dbb92b8..afb8e78 100644 --- a/022-custom-smtp-and-email-templates.md +++ b/022-custom-smtp-and-email-templates.md @@ -39,6 +39,8 @@ It will accept following parameters - **username** : string - SMTP server user name - **password** : string - SMTP server password +SMTP configuration will be validated by creating a PHP mailer with the given credentials. + **PATCH /v1/projects/:projectId/template/sms/:type/:locale** - updates custom SMS templates - **type** : string - required - template type