Add email and AWS SES notification guides (#28)

* Add notification guides for email and Amazon SES

Author: hsoerensen

docs/notification-guides/amazon-ses.md

@@ -0,0 +1,69 @@
+# Email
+
+!!! info
+    Follow guidance on [enabling notifications](../../operating/setup-notifications/) first.
+
+## What It Is?
+
+[Amazon SES](https://aws.amazon.com/ses/) is a cost-effective email service that offers cost-effective email sending,
+at a cost of $0.10 per 1,000 emails.
+No monthly fees or upfront commitments are required.
+
+## Supported Ways To Receive Notifications
+
+- Email
+
+## What To Know Before You Start
+
+Familiarity with DNS and Amazon AWS is required, including appropriately securing your AWS account.
+
+## Configuring Amazon SES
+
+!!! info
+    Full configuration options and capabilities are available via [Apprise](https://github.com/caronc/apprise/wiki/Notify_pushbullet)
+
+1. Create an IAM user that has access to SES. The user should have a programmatic access key and secret key.
+2. Attach the [following policy](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/control-user-access.html) to the user:
+    ```json
+       {
+         "Version":"2012-10-17",
+         "Statement":[
+           {
+             "Effect":"Allow",
+             "Action":[
+               "ses:SendEmail",
+               "ses:SendRawEmail"
+             ],
+             "Resource":"*"
+           }
+         ]
+       }
+    ```
+3. Set up Amazon SES for your domain, which includes domain verification and DKIM record setup.
+   DKIM verification is automated with Route 53.
+For other DNS providers, manually add the necessary DNS CNAME records for DKIM verification.
+4. Verify your domain to start sending emails, which can take from minutes and up to 72 hours.
+5. Copy the example `notification.yml.example` file to the `notification.yml` file:
+
+    ```bash
+    cp ~/voi/docker/notification.yml.example ~/voi/docker/notification.yml
+    ```
+
+6. Update the **NOTIFICATION_URLS** value in `notification.yml` file with your Email mailto:// link
+
+    ``` yaml
+    NOTIFICATION_URLS="ses://<sender_account>@<sender_domain>/<access_key>/access_secret>/<region>/<recipient_email>/?from=<sender_name>"
+    ```
+
+    If the sender name contains whitespaces make sure you substitute them with `%20` in the `from` parameter.
+
+!!! tip
+    If you want to use multiple notification mechanisms, separate them with a comma.
+    For example, to use both Discord and Email for notification, you would set the **NOTIFICATION_URLS** value
+    in the `notification.yml` file to:
+
+       ```yaml
+       NOTIFICATION_URLS="discord://<webhook_id>/<webhook_token>,ses://<sender_account>@<sender_domain>/<access_key>/access_secret>/<region>/<recipient_email>/?from=<sender_name>"
+       ```
+
+--8<-- "notification-guides/notification-test.md"

docs/notification-guides/email.md

@@ -0,0 +1,66 @@
+# Email
+
+!!! info
+    Follow guidance on [enabling notifications](../../operating/setup-notifications/) first.
+
+## What It Is?
+
+Notifications can be sent via email.
+
+## Supported Ways To Receive Notifications
+
+- Email
+
+## What To Know Before You Start
+
+Email sending is done by using an existing email provider that offers SMTP services.
+This is a simple and easy way to send notifications to your email address, but may require some setup.
+
+If you own your own domain, and control DNS settings,
+you can use a service such as [Amazon SES](amazon-ses.md) to send email in a cost-effective way.
+
+If you do not own your own domain,
+or are unable to control DNS settings, you can use a free email provider such as live.com to send email.
+Some providers (e.g., Gmail)
+have security mechanisms in place that may prevent you from easily sending email using SMTP.
+
+Learn more at [Apprise Notify Email](https://github.com/caronc/apprise/wiki/Notify_email)
+
+### Why Don't You Offer a Free Email Notification Service?
+
+Collecting and storing email addresses, that would be associated with specific Voi accounts
+would require us to comply with data protection laws, which would be a significant burden
+for us to manage.
+The current setup allows you to use your own email provider, and we do not have to manage any personal data.
+
+## Using Live.com to Send Email
+
+!!! note
+      Full configuration options and capabilities are available via [Apprise](https://github.com/caronc/apprise/wiki/Notify_pushbullet)
+        and may be required depending on your email provider and/or SMTP configuration.
+
+1. Create a new email account used only for notifications. This is to ensure that your main email account is not compromised if the notification email account is compromised.
+2. Configure the notification email account to forward emails to your main email account.
+3. Set your notification email to have a strong password with no special characters. This is to ensure that the password can be used in the `notification.yml` file without needing to escape special characters.
+4. Copy the example `notification.yml.example` file to the `notification.yml` file:
+
+    ```bash
+    cp ~/voi/docker/notification.yml.example ~/voi/docker/notification.yml
+    ```
+
+5. Update the **NOTIFICATION_URLS** value in `notification.yml` file with your Email mailto:// link
+
+    ``` yaml
+    NOTIFICATION_URLS="mailto:///example:[email protected]?from=Voi%20Notification"
+    ```
+
+!!! tip
+      If you want to use multiple notification mechanisms, separate them with a comma.
+      For example, to use both Discord and Email for notification, you would set the **NOTIFICATION_URLS** value
+      in the `notification.yml` file to:
+
+       ```yaml
+       NOTIFICATION_URLS="discord://<webhook_id>/<webhook_token>,mailto:///example:[email protected]?from=Voi%20Notification"
+       ```
+
+--8<-- "notification-guides/notification-test.md"

docs/notification-guides/notification-test.md

@@ -0,0 +1,19 @@
+## Testing Your Notification Configuration
+
+With your configuration in place, it's now time to test it.
+
+First, we need to make sure that Voi Swarm picks up your changes to notification.yml.
+To do this, rerun the installation script:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/VoiNetwork/voi-swarm/main/install.sh)"
+```
+
+After the script has run and applied changes to the environment, we need to send a test notification to make sure
+everything is working as expected.
+
+To do this, run the following command:
+
+```bash
+~/voi/bin/notification-test
+```

docs/notification-guides/pushbullet.md

@@ -43,22 +43,4 @@
     NOTIFICATION_URLS="discord://<webhook_id>/<webhook_token>,pbul://<access_token>"
     ```
 
-## Testing Your Notification Configuration
-
-With your configuration in place it's now time to test it.
-
-First we need to make sure that your changes to notification.yml is picked up by the stack.
-To do this, rerun the installation script:
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/VoiNetwork/voi-swarm/main/install.sh)"
-```
-
-After the script has run and applied changes to the environment we need to send a test notification to make sure
-everything is working as expected.
-
-To do this, run the following command:
-
-```bash
-~/voi/bin/notification-test
-```
+--8<-- "notification-guides/notification-test.md"

mkdocs.yml

@@ -70,6 +70,9 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.superfences
   - footnotes
+  - pymdownx.snippets:
+      base_path: "docs"
+      check_paths: true
   - pymdownx.tabbed:
       alternate_style: true
       slugify: !!python/object/apply:pymdownx.slugs.slugify
@@ -105,6 +108,8 @@ nav:
         - Participation keys: operating/participation-keys.md
         - Setup notifications: operating/setup-notifications.md
   - Notification Guides:
+      - Amazon SES: notification-guides/amazon-ses.md
+      - Email: notification-guides/email.md
       - Pushbullet: notification-guides/pushbullet.md
   - Provider Guidance: provider-guidance.md
   - Migrating to Voi Swarm: migrating.md