From d4fe1260c1ea306b967eff746544b5e6ce4c09fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9gis=20Behmo?= <regis@behmo.com>
Date: Tue, 23 Nov 2021 18:16:51 +0100
Subject: [PATCH] docs: add tutorial on using Google Mail as an SMTP server

The tutorial comes from the feedback of multiple users, including:
https://discuss.overhang.io/t/google-smtp-not-working/2143
---
 docs/tutorials.rst             |  1 +
 docs/tutorials/google-smtp.rst | 42 ++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/tutorials/google-smtp.rst

diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index 2bb558f..0bd5103 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -9,6 +9,7 @@ Open edX customization
 
    tutorials/theming
    tutorials/edx-platform-settings
+   tutorials/google-smtp
    tutorials/nightly
 
 System administration
diff --git a/docs/tutorials/google-smtp.rst b/docs/tutorials/google-smtp.rst
new file mode 100644
index 0000000..c45df2b
--- /dev/null
+++ b/docs/tutorials/google-smtp.rst
@@ -0,0 +1,42 @@
+Using Google Mail as an SMTP server
+===================================
+
+By default, Tutor comes with a simple SMTP server for sending emails. Such a server has an important limitation: it does not implement mailing good practices, such as DKIM or SPF. As a consequence. the emails you send might be flagged as spam by their recipients. Thus, you might want to disable the SMTP server and run your own, for instance using your Google Mail account.
+
+.. warning::
+  Google Mail SMTP servers come with their own set of limitations. For instance, you are limited to sending 500 emails a day. Reference: https://support.google.com/mail/answer/22839
+
+You should authorize third party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255
+
+Then, check that you can reach the Google Mail SMTP service from your own server::
+
+    $ telnet smtp.gmail.com 587
+
+If you get ``Connected to smtp.gmail.com.`` then it means that you can successfully reach the Google Mail SMTP servers. If not, you will have to reconfigure your firewall.
+
+To exit the ``telnet`` shell, type ``ctrl+]``, then ``ctrl+d``.
+
+Thenm, disable the SMTP server that comes with Tutor::
+
+    $ tutor config save --set RUN_SMTP=false
+
+Configure credentials to access your SMTP server::
+
+    $ tutor config save \
+      --set SMTP_HOST=smtp.gmail.com \
+      --set SMTP_PORT=587 \
+      --set SMTP_USE_SSL=false  \
+      --set SMTP_USE_TLS=true \
+      --set SMTP_USERNAME=YOURUSERNAME@gmail.com \
+      --set SMTP_PASSWORD='YOURPASSWORD'
+
+Don't forget to replace your email address and password in the prompt above. If your email password contains special characters, you might have to escape them.
+
+Then, restart your platform::
+
+    $ tutor local quickstart
+
+That's it! You can send a test email with the following command::
+
+    $ tutor local run --no-deps lms ./manage.py lms shell -c \
+      "from django.core.mail import send_mail; send_mail('test subject', 'test message', 'YOURUSERNAME@gmail.com', ['YOURRECIPIENT@domain.com'])"