Rewrite the email gateway integration instructions.

changelog.md

@@ -10,3 +10,4 @@ All notable changes to this project will be documented in this file.
 - Added new endpoint to support Google auth on mobile.
 - Fixed desktop notifications in modern Firefox.
 - Fixed several installation issues for both production and development environments.
+- Improved documentation for outgoing SMTP and the email mirror integration.

zproject/local_settings_template.py

@@ -150,42 +150,47 @@ ENABLE_GRAVATAR = True
 
 ### EMAIL GATEWAY INTEGRATION
 
-# The email gateway provides, for each stream, an email address that
+# The Email gateway integration supports sending messages into Zulip
-# you can send email to in order to have the email's content be posted
+# by sending an email.  This is useful for receiving notifications
-# to that stream.  Emails received at the per-stream email address
+# from third-party services that only send outgoing notifications via
-# will be converted into a Zulip message
+# email.  Once this integration is configured, each stream will have
-
+# an email address documented on the stream settings page an emails
-# There are two ways to make use of local email mirroring:
+# sent to that address will be delivered into the stream.
+#
+# There are two ways to configure email mirroring in Zulip:
 #  1. Local delivery: A MTA runs locally and passes mail directly to Zulip
 #  2. Polling: Checks an IMAP inbox every minute for new messages.
-
-# A Puppet manifest for local delivery via Postfix is available in
-# puppet/zulip/manifests/postfix_localmail.pp. To use the manifest, add it to
-# puppet_classes in /etc/zulip/zulip.conf. This manifest assumes you'll receive
-# mail addressed to the hostname of your Zulip server.
 #
-# Users of other mail servers will need to configure it to pass mail to the
+# The local delivery configuration is preferred for production because
-# email mirror; see `python manage.py email-mirror --help` for details.
+# it supports nicer looking email addresses and has no cron delay,
-
+# while the polling mechanism is better for testing/developing this
-# The email address pattern to use for auto-generated stream emails
+# feature because it doesn't require a public-facing IP/DNS setup.
-# The %s will be replaced with a unique token, and the resulting email
-# must be delivered to the EMAIL_GATEWAY_IMAP_FOLDER of the
-# EMAIL_GATEWAY_LOGIN account below, or piped in to the email-mirror management
-# command as indicated above.
 #
-# Example: zulip+%s@example.com
+# The main email mirror setting is the email address pattern, where
+# you specify the email address format you'd like the integration to
+# use.  It should be one of the following:
+#   %s@zulip.example.com (for local delivery)
+#   username+%s@example.com (for polling if EMAIL_GATEWAY_LOGIN=username@example.com)
 EMAIL_GATEWAY_PATTERN = ""
-
-
-# The following options are relevant if you're using mail polling.
 #
-# A sample cron job for mail polling is available at puppet/zulip/files/cron.d/email-mirror
+# If you are using local delivery, EMAIL_GATEWAY_PATTERN is all you need
+# to change in this file.  You will also need to enable the Zulip postfix
+# configuration to support local delivery by adding
+#   , zulip::postfix_localmail
+# to puppet_classes in /etc/zulip/zulip.conf.
+#
+# If you are using polling, you will need to setup an IMAP email
+# account dedicated to Zulip email gateway messages.  The model is
+# that users will send emails to that account via an address of the
+# form username+%s@example.com (which is what you will set as
+# EMAIL_GATEWAY_PATTERN); your email provider should deliver those
+# emails to the username@example.com inbox.  Then you run in a cron
+# job `./manage.py email-mirror` (see puppet/zulip/files/cron.d/email-mirror),
+# which will check that inbox and batch-process any new messages.
+#
+# You will need to configure authentication for the email mirror
+# command to access the IMAP mailbox below.
 #
-# The Zulip username of the bot that the email pattern should post as.
-# Example: emailgateway@example.com
-EMAIL_GATEWAY_BOT = ""
-
-# Configuration of the email mirror mailbox
 # The IMAP login and password
 EMAIL_GATEWAY_LOGIN = ""
 EMAIL_GATEWAY_PASSWORD = ""