Add documentation for the app architecture and configuration

apps/emails-and-messages/docs/architecture.md

@@ -0,0 +1,26 @@
+# Data sequences
+
+## SMTP
+
+```mermaid
+sequenceDiagram
+    Saleor API ->>+ EAM App: Order created
+    EAM App ->>+ EAM App: Choose configuration based on event channel
+    EAM App ->> EAM App: Use Handlebars to generate MJML template based on event payload
+    EAM App ->>- EAM App: Convert MJML to HTML
+    EAM App ->> SMTP Server: Send email
+    SMTP Server ->> Customer: Send email
+    EAM App ->>- Saleor API: Email has been send
+```
+
+## Sendgrid
+
+```mermaid
+sequenceDiagram
+    Saleor API ->>+ EAM App: Order created
+    EAM App ->>+ EAM App: Choose configuration based on event channel
+    EAM App ->> Sendgrid API: Send template ID and event payload
+    Sendgrid API ->> Sendgrid API: Generate email
+    Sendgrid API ->> Customer:  Send email
+    EAM App ->>- Saleor API: Email has been send
+```

apps/emails-and-messages/docs/introduction.md

@@ -0,0 +1,43 @@
+# Introduction
+
+## Glossary
+
+- **Saleor API** - instance of Saleor Shop
+- **Saleor events** - After events like creating new order or user registration Saleor API sends notification to EAM app with data describing it. When configuring the app, user can specify which events should send an email to the customers
+- **EAM** - Emails and Messages app
+- **SMTP** - Protocol used for sending emails
+- **Sendgrid** - Email sending service
+- **Configuration** - Group of settings related to one of the providers. User can specify many configurations.
+
+## How emails are sent?
+
+Before any of the messages are sent, the application have to be installed and configured. After those steps are completed, application wait for the event to happen:
+
+```mermaid
+sequenceDiagram
+    Saleor API ->>+ EAM App: Order created
+    EAM App ->>+ EAM App: Choose active configuration based on event channel
+    EAM App ->> EAM App: Choose event related settings
+    EAM App ->> Provider API: Send email data
+    Provider API ->> Customer: Deliver email
+```
+
+1. Customer places order in the shop
+1. Saleor API notify the EAM App
+1. The application choose the configuration and send data provider (Sendgrid, SMTP, etc.)
+1. Provider delivers email to the customer
+
+# How configurations are determined
+
+1. Event webhook arrives to the app
+1. Get all configurations
+1. Filter out not active
+1. Filter out configurations not assigned to this channel:
+   - If `channel override` option is **not set**, all channels are considered as assigned to this configurations
+   - If `channel override` option is **set** and `exclude channels` are provided, filter out configuration if **it's on** this list
+   - If `channel override` option is **set** and `include channels` are provided, filter out configuration if **it's not on** this list
+1. At this point we have active configurations which are intended to use with channel. Please note, at the same time multiple configurations/providers can be used for one event. Now we have to determine configuration assigned to payload event
+1. Check if event configuration **is active**
+   - if **it's active**, use provided templates, etc and send the message
+   - if **it's not active**, no message will be sent
+1. Now the application will send the message using chosen provider

apps/emails-and-messages/docs/sendgrid.md

@@ -0,0 +1,33 @@
+# Sendgrid
+
+## Creating configuration
+
+Before you start, configure your Sendgrid Account:
+
+- Generate **API key**
+
+  - [Sendgrid documentation about setting up API keys](https://docs.sendgrid.com/for-developers/sending-email/brite-verify#creating-a-new-api-key)
+
+- Create **Sender**
+
+  - [Sendgrid documentation about senders](https://docs.sendgrid.com/ui/sending-email/senders)
+
+- For every event message you want to sent to the customers, create **Dynamic template**
+  - [Sendgrid documentation for dynamic templates](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates#design-a-dynamic-template)
+
+Now you can configure EAM:
+
+1. In the Saleor Dashboard navigate to the apps section
+1. Install Emails and Messages app
+1. After installation, click app name
+1. Click on `Add provider`
+1. Choose `Sendgrid`
+1. Provide configuration name and API key
+1. Click on `Save provider`
+1. Application will redirect automatically to the configuration details
+1. Choose sender
+1. Click on `Save provider`
+1. In the events section assign dynamic templates to events
+1. Click on `Save provider`
+
+Application is now configured.

apps/emails-and-messages/docs/smtp.md

@@ -0,0 +1,61 @@
+# SMTP provider
+
+To use this provider, you will need SMTP server credentials. Email templates are created using [MJML](https://mjml.io/) language and can be edited in dashboard. Dynamic parts of the email (for example number of the order) can be added using [Handlebars](https://handlebarsjs.com/).
+
+## Before you start - server credentials
+
+Using provider requires access to SMTP server. Depending on your needs, choose one of our recommendations.
+
+### For production environments
+
+- [Amazon SES](https://aws.amazon.com/ses/)
+- [Mailgun](https://www.mailgun.com/)
+- [Mailtrap](https://mailtrap.io/)
+
+### For testing
+
+There are dedicated services for testing email delivery. One of them is [Mailtrap](https://mailtrap.io/).
+
+> **Note**
+> Such services capture emails and display it in their interface for inspection. Original addressee should not receive any message.
+
+To get credentials needed to configuring the app, follow [the guide](https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing).
+
+### For local development
+
+If you are developer working on EAM and don't want to use external service, you can use Mailhog which comes pre configured in this repository.
+
+Requirements:
+
+- Docker is installed
+- `docker compose` command is available
+
+To start the service:
+
+1. Open EAM app folder in terminal
+1. Use command `docker compose up`
+
+Mailhog will start SMTP server and web interface. Now you can update provider configuration:
+
+- Host: `localhost`
+- Port: `1025`
+- The rest can be left empty
+
+All emails will be captured by the MailHog service. To inspect emails, open `http://localhost:8025/` in your browser.
+
+# Creating configuration
+
+1. In the Saleor Dashboard navigate to the apps section
+1. Install Emails and Messages app
+1. After installation, click app name
+1. Click on `Add provider`
+1. Choose `SMTP`
+1. Provide SMTP server credentials created in previous step
+1. Click on `Save provider`
+1. Application will redirect automatically to the configuration details
+1. Enter sender details, which will be displayed as author of the emails for your customers
+1. Click on `Save provider`
+1. In the events section choose which of the emails should be sent. You can also modify template of the emails.
+1. Click on `Save provider`
+
+Now application is configured and emails will be sent.

apps/emails-and-messages/docs/troubleshooting.md

@@ -0,0 +1,32 @@
+# Troubleshooting
+
+## For all providers
+
+- [ ] Make sure the configuration is activated
+  1. Go to configuration details
+  1. In the `Status and name` section, `Active` should be checked
+- [ ] Configuration is enabled for the channel
+  1. Go to configuration details
+  1. If channel assignment is overwritten, ensure channel the event originated from is not excluded
+- [ ] Ensure the sender details are filled in
+  1. Go to configuration details
+  1. Fill fields in the `Sender` section
+- [ ] Event is activated
+  1. Go to configuration details
+  1. In the `Events` section, `Active` should be checked for event you are investigating
+
+## SMTP
+
+- [ ] Template preview is rendering
+  1. Go to configuration details
+  1. In the `Events` section, click on `Edit` for event you are investigating
+  1. Template on the right hand side should be rendering properly
+
+## Sendgrid
+
+- [ ] Sandbox mode is not active
+  1. Go to configuration details
+  1. In the `API connection` section, sandbox mode should not be activated
+- [ ] API key is still active
+- [ ] Sender is configured and available
+- [ ] Dynamic templates are configured and available