paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-02 21:13:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs/production: Make an editing pass through the SMTP doc.

Browse Source 
In addition to many small edits for formatting and clarity, a few more
significant changes:

* In the main instructions, refer specifically to restarting the
  server and to testing that the config works.

* Add SendGrid to the recommended list, as it seems like people
  give it a somewhat stronger reputation these days than Mailgun.

* Discuss EMAIL_USE_TLS and EMAIL_PORT along with host, user, and
  password in the "free services" section.  Though those bullets feel
  kind of duplicative to me already.
This commit is contained in:
Greg Price
2018-04-05 17:39:26 -07:00
committed by Tim Abbott
parent b9f1f9c0ae
commit 6396b3aef7
1 changed files with 61 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
docs/production/email.md
View File

@@ -18,6 +18,13 @@ email addresses and send notifications.
`/etc/zulip/zulip-secrets.conf` by setting `email_password`. For
example: `email_password = abcd1234`.
Like any other change to the Zulip configuration, be sure to
[restart the server](settings.html) to make your changes take
effect.
4. Test that your configuration is working. See the test command in
the [Troubleshooting](#troubleshooting) section below. If it's not
working, see the suggestions in that section.
## Email services
@@ -25,22 +32,27 @@ email addresses and send notifications.
For sending outgoing email from your Zulip server, we highly recommend
using a "transactional email" service like
[Mailgun](https://documentation.mailgun.com/en/latest/quickstart-sending.html#send-via-smtp)
or for AWS users,
[SendGrid](https://sendgrid.com/docs/API_Reference/SMTP_API/integrating_with_the_smtp_api.html),
[Mailgun](https://documentation.mailgun.com/en/latest/quickstart-sending.html#send-via-smtp),
or, for AWS users,
[Amazon SES](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html).
These services are designed to send email from servers, and are by far
the easiest way to get outgoing email working reliably.
If you don't have an existing outgoing SMTP provider, don't worry!
Both of the options we recommend above (as well as dozens of other
services) have free options; we recommend Mailgun as the easiest to
get setup with. Once you've signed up, you'll want to find the
service's provided "SMTP credentials", and configure Zulip as follows:
Each of the options we recommend above (as well as dozens of other
services) have free options. Once you've signed up, you'll want to
find the service's provided "SMTP credentials", and configure Zulip as
follows:
* The hostname as `EMAIL_HOST = 'smtp.mailgun.org'` in `/etc/zulip/settings.py`
* The username as `EMAIL_HOST_USER = 'username@example.com` in
* The hostname like `EMAIL_HOST = 'smtp.mailgun.org'` in `/etc/zulip/settings.py`
* The username like `EMAIL_HOST_USER = 'username@example.com` in
`/etc/zulip/settings.py`.
* The password as `email_password = abcd1234` in `/etc/zulip/zulip-secrets.conf`.
* The TLS setting as `EMAIL_USE_TLS = True` in
`/etc/zulip/settings.py`, for most providers
* The port as `EMAIL_PORT = 587` in `/etc/zulip/settings.py`, for most
providers
* The password like `email_password = abcd1234` in `/etc/zulip/zulip-secrets.conf`.
### Using Gmail for outgoing email
@@ -60,24 +72,26 @@ how to make it work:
* Note also that the rate limits for Gmail are also quite low
(e.g. 100 / day), so it's easy to get rate-limited if your server
has significant traffic. For more active servers, we recommend
moving to a free account from a transaction email service.
moving to a free account on a transactional email service.
### Logging outgoing email to a file for prototyping
If for prototyping, you don't want to bother setting up an email
provider, you can add to `/etc/zulip/settings.py` the following:
For prototyping, you might want to proceed without setting up an email
provider. If you want to see the emails Zulip would have sent, you
can log them to a file instead.
To do so, add these lines to `/etc/zulip/settings.py`:
```
EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'
EMAIL_FILE_PATH = '/var/log/zulip/emails'
```
Outgoing emails that Zulip would have sent will just be written to
files in `/var/log/zulip/emails/`. This is enough to get you through
initial user registration without an SMTP provider.
Then outgoing emails that Zulip would have sent will just be written
to files in `/var/log/zulip/emails/`.
Remember to delete this configuration and restart the server if you
later setup a real SMTP provider!
Remember to delete this configuration (and restart the server) if you
later set up a real SMTP provider!
## Troubleshooting
@@ -91,19 +105,22 @@ su zulip
If it doesn't throw an error, it probably worked; you can confirm by
checking your email.
It's important to test, because outgoing email often doesn't work the
first time. Common causes of failures are:
If it doesn't work, check these common failure causes:
* Your hosting provider blocking outgoing SMTP traffic in its
default firewall rules. Check whether `EMAIL_PORT` is blocked in your
hosting provider's firewall.
* Forgetting to put the password in `/etc/zulip/zulip-secrets.conf`.
* Typos in transcribing the username or password.
* Your hosting provider may block outgoing SMTP traffic in its default
firewall rules. Check whether the port `EMAIL_PORT` is blocked in
your hosting provider's firewall.
Once you have it working from the management command, remember to
restart your Zulip server using
`/home/zulip/deployments/current/scripts/restart-server` so that the running
server is using the latest configuration.
* Make sure you set the password in `/etc/zulip/zulip-secrets.conf`.
* Check the username and password for typos.
* Be sure to restart your Zulip server after editing either
`settings.py` or `zulip-secrets.conf`, using
`/home/zulip/deployments/current/scripts/restart-server` .
Note that the `manage.py` command above will read the latest
configuration from the config files, even if the server is still
running with an old configuration.
### Advanced troubleshooting
@@ -111,22 +128,27 @@ Here are a few final notes on what to look at when debugging why you
aren't receiving emails from Zulip:
* Most transactional email services have an "outgoing email" log where
you can inspect the emails that reached the service, whether it was
flagged as spam, etc.
you can inspect the emails that reached the service, whether an
email was flagged as spam, etc.
* Starting with Zulip 1.7, Zulip logs an entry in
`/var/log/zulip/send_email.log` whenever it attempts to send an
email, including whether the request succeeded or failed.
email. The log entry includes whether the request succeeded or failed.
* If attempting to send an email throws an exception, a traceback
should be in `/var/log/zulip/errors.log`, along with any other
exceptions Zulip encounters.
* Zulip's email sending configuration is based on the standard Django
[SMTP backend](https://docs.djangoproject.com/en/1.10/topics/email/#smtp-backend)
[SMTP backend](https://docs.djangoproject.com/en/2.0/topics/email/#smtp-backend)
configuration. So if you're having trouble getting your email
provider working, you may want to search for documentation related
to using your email provider with Django. The one thing we've
changed from the defaults is reading the email password from the
`email_password` entry in the Zulip secrets file, as part of our
policy of not having any secret information in the
`/etc/zulip/settings.py` file. In other words, if Django
documentation references setting `EMAIL_HOST_PASSWORD`, you should
instead set `email_password` in `/etc/zulip/zulip-secrets.conf`.
to using your email provider with Django.
The one thing we've changed from the Django defaults is that we read
the email password from the `email_password` entry in the Zulip
secrets file, as part of our policy of not having any secret
information in the `/etc/zulip/settings.py` file. In other words,
if Django documentation references setting `EMAIL_HOST_PASSWORD`,
you should instead set `email_password` in
`/etc/zulip/zulip-secrets.conf`.