From a001fc1b5718f47725fc339d5db3a6c24a14519c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nuno=20G=C3=B3is?= <github@nunogois.com>
Date: Tue, 14 Nov 2023 12:53:34 +0000
Subject: [PATCH] docs: troubleshooting email service (#5333)

https://linear.app/unleash/issue/SR-173/discussion-question-notification-from-email-doesnt-work

Adds a troubleshooting guide for [email
service](https://docs.getunleash.io/using-unleash/deploy/email-service),
which includes some knowledge shared in this discussion:
https://github.com/orgs/Unleash/discussions/5323#discussioncomment-7554431
---
 .../using-unleash/deploy/email-service.md     |  4 +++
 .../troubleshooting/email-service.md          | 35 +++++++++++++++++++
 website/sidebars.js                           |  1 +
 3 files changed, 40 insertions(+)
 create mode 100644 website/docs/using-unleash/troubleshooting/email-service.md

diff --git a/website/docs/using-unleash/deploy/email-service.md b/website/docs/using-unleash/deploy/email-service.md
index 1366c44ca5..ed88bfef76 100644
--- a/website/docs/using-unleash/deploy/email-service.md
+++ b/website/docs/using-unleash/deploy/email-service.md
@@ -46,3 +46,7 @@ unleash.start({
   },
 });
 ```
+
+## Troubleshooting {#troubleshooting}
+
+For troubleshooting tips, please refer to the [email service troubleshooting guide](../troubleshooting/email-service.md).
diff --git a/website/docs/using-unleash/troubleshooting/email-service.md b/website/docs/using-unleash/troubleshooting/email-service.md
new file mode 100644
index 0000000000..69d5bb04a8
--- /dev/null
+++ b/website/docs/using-unleash/troubleshooting/email-service.md
@@ -0,0 +1,35 @@
+---
+title: The email service is not working correctly on my self-hosted Unleash instance
+---
+
+When setting up your self-hosted Unleash instance, one of the available options is to configure an [email service](https://docs.getunleash.io/using-unleash/deploy/email-service) that will allow Unleash to send reset password and welcome emails to users.
+
+Here's how to troubleshoot some common issues related to the email service.
+
+## Configuration
+
+The most common issues arise from misconfiguration. Please refer to the following documentation for guidance:
+- [Email service](https://docs.getunleash.io/using-unleash/deploy/email-service)
+- [Configuring Unleash](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash)
+
+You should double check that the details in your configuration look correct.
+
+## Invalid URL error
+
+Make sure that the [UNLEASH_URL](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash#unleash-url) variable is correctly set to a valid URL. This should be set to the public discoverable URL of your Unleash instance, and it should include the protocol (http or https).
+
+Examples:
+- Subdomain: `https://unleash.mysite.com`
+- Subpath: `https://mysite.com/unleash`
+
+## SSL-related errors
+
+### SMTP TLS port
+
+Please double check that you're trying to reach your SMTP server on the TLS port, typically `587`.
+
+### Custom SSL certificate
+
+If you're using your own SMTP server which uses a custom SSL certificate, you will need to tell Unleash to trust that certificate. You can do this by setting the [NODE_EXTRA_CA_CERTS](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash#node-extra-ca-certs) variable to the path of the certificate file.
+
+This is usually done by mounting the custom certificate in a volume, and then setting `NODE_EXTRA_CA_CERTS` to the absolute path in the container where it can find the certificate. For example, if you mount it to `/var/certs`, you should set `NODE_EXTRA_CA_CERTS` to something like `/var/certs/mycert.crt`.
diff --git a/website/sidebars.js b/website/sidebars.js
index c6640217b8..aac54593fe 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -416,6 +416,7 @@ module.exports = {
                     },
                     items: [
                         'using-unleash/troubleshooting/cors',
+                        'using-unleash/troubleshooting/email-service',
                         'using-unleash/troubleshooting/feature-not-available',
                         'using-unleash/troubleshooting/flag-exposure',
                         'using-unleash/troubleshooting/flag-not-returned',