Add documentation about Mailgun setup fixes #1705

docs/deployment-on-heroku.rst

@@ -51,6 +51,11 @@ Run these commands to deploy the project to Heroku:
     heroku open
 
 
+.. warning::
+
+    .. include:: mailgun.rst
+
+
 Optional actions
 ----------------
 

docs/deployment-with-docker.rst

@@ -43,6 +43,11 @@ You will probably also need to setup the Mail backend, for example by adding a `
 .. _Mailgun: https://mailgun.com
 
 
+.. warning::
+
+    .. include:: mailgun.rst
+
+
 Optional: Use AWS IAM Role for EC2 instance
 -------------------------------------------
 

docs/mailgun.rst

@@ -0,0 +1,13 @@
+If your email server used to send email isn't configured properly (Mailgun by default),
+attempting to send an email will cause an Internal Server Error.
+
+By default, django-allauth is setup to `have emails verifications mandatory`_,
+which means it'll send a verification email when an unverified user tries to
+log-in or when someone tries to sign-up.
+
+This may happen just after you've setup your Mailgun account, which is running in a
+sandbox subdomain by default. Either add your email to the list of authorized recipients
+or verify your domain.
+
+
+.. _have emails verifications mandatory: https://django-allauth.readthedocs.io/en/latest/configuration.html?highlight=ACCOUNT_EMAIL_VERIFICATION

docs/troubleshooting.rst

@@ -11,5 +11,7 @@ This page contains some advice about errors and problems commonly encountered du
 
 #. New apps not getting created in project root: This is the expected behavior, because cookiecutter-django does not change the way that django startapp works, you'll have to fix this manually (see `#1725`_)
 
+#. .. include:: mailgun.rst
+
 .. _#528: https://github.com/pydanny/cookiecutter-django/issues/528#issuecomment-212650373
 .. _#1725: https://github.com/pydanny/cookiecutter-django/issues/1725#issuecomment-407493176