Update inbound and outbound email documentation

Summary: Fixes T8636. Mention Herald for inbound, update some outbound stuff, do some language / organization tweaks.

Test Plan: Read documentation.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T8636

Differential Revision: https://secure.phabricator.com/D19973

src/docs/user/configuration/configuring_inbound_email.diviner

@@ -4,10 +4,36 @@
 This document contains instructions for configuring inbound email, so users
 may interact with some Phabricator applications via email.
 
-= Preamble =
+Preamble
+========
 
-This can be extremely difficult to configure correctly. This is doubly true if
+Phabricator can process inbound mail in two general ways:
-you use a local MTA.
+
+**Handling Replies**: When users reply to email notifications about changes,
+Phabricator can turn email into comments on the relevant discussion thread.
+
+**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
+to create new objects (like tasks) when users send email.
+
+In either case, users can interact with objects via `!commands` mail commands
+to apply a broader set of changes to objects (like adding subscribers, closing
+tasks, or changing priorities) beyond simply commenting.
+
+To configure inbound mail, you will generally:
+
+  - Configure some mail domain to submit mail to Phabricator for processing.
+  - For handling replies, set `metamta.reply-handler-domain` in configuration.
+  - For handling email that creates objects, configure inbound addresses in the
+    relevant application.
+
+See below for details on each of these steps.
+
+
+Approaches
+==========
+
+Inbound mail can be extremely difficult to configure correctly. This is doubly
+true if you use a local MTA.
 
 There are a few approaches available:
 
@@ -22,11 +48,13 @@ The remainder of this document walks through configuring Phabricator to
 receive mail, and then configuring your chosen transport to deliver mail
 to Phabricator.
 
-= Configuring Phabricator =
+
+Configuring "Reply" Email
+=========================
 
 By default, Phabricator uses a `noreply@phabricator.example.com` email address
-as the 'From' (configurable with `metamta.default-address`) and sets
+as the "From" (configurable with `metamta.default-address`) and sets
-'Reply-To' to the user generating the email (e.g., by making a comment), if the
+"Reply-To" to the user generating the email (e.g., by making a comment), if the
 mail was generated by a user action. This means that users can reply (or
 reply-all) to email to discuss changes, but the conversation won't be recorded
 in Phabricator and users will not be able to take actions like claiming tasks or
@@ -44,22 +72,40 @@ etc. over email.
 If you don't want Phabricator to take up an entire domain (or subdomain) you
 can configure a general prefix so you can use a single mailbox to receive mail
 on. To make use of this set `metamta.single-reply-handler-prefix` to the
-prefix of your choice, and Phabricator will prepend this to the 'Reply-To'
+prefix of your choice, and Phabricator will prepend this to the "Reply-To"
 mail address. This works because everything up to the first (optional) '+'
-character in an email-address is considered the receiver, and everything
+character in an email address is considered the receiver, and everything
 after is essentially ignored.
 
-You can also set up application email addresses to allow users to create
+
-application objects via email. For example, you could configure
+Configuring "Create" Email
-`bugs@phabricator.example.com` to create a Maniphest task out of any email
+==========================
-which is sent to it. To do this, see application settings for a given
+
-application at
+You can set up application email addresses to allow users to create objects via
+email. For example, you could configure `bugs@phabricator.example.com` to creat
+a Maniphest task out of any email which is sent to it.
+
+You can find application email settings for each application at:
 
 {nav icon=home, name=Home >
-name=Applications >
+Applications >
-icon=cog, name=Settings}
+type=instructions, name="Select an Application" >
+icon=cog, name=Configure}
 
-= Security =
+Not all application support creating objects via email.
+
+In some applications, including Maniphest, you can also configure Herald rules
+with the `[ Content source ]` and/or `[ Receiving email address ]` fields to
+route or handle objects based on which address mail was sent to.
+
+You'll also need to configure the actual mail domain to submit mail to
+Phabricator by following the instructions below. Phabricator will let you add
+any address as an application address, but can only process mail which is
+actually delivered to it.
+
+
+Security
+========
 
 The email reply channel is "somewhat" authenticated. Each reply-to address is
 unique to the recipient and includes a hash of user information and a unique
@@ -99,7 +145,9 @@ signatures are sufficient to authenticate the sender under your configuration,
 or you are willing to require all users to sign their email), file a feature
 request.
 
-= Testing and Debugging Inbound Email =
+
+Testing and Debugging Inbound Email
+===================================
 
 You can use the `bin/mail` utility to test and review inbound mail. This can
 help you determine if mail is being delivered to Phabricator or not:
@@ -116,7 +164,9 @@ if your inbound email configuration is incorrect or even disabled.
 
 Run `bin/mail help <command>` for detailed help on using these commands.
 
-= Mailgun Setup =
+
+Mailgun Setup
+=============
 
 To use Mailgun, you need a Mailgun account. You can sign up at
 <http://www.mailgun.com>. Provided you have such an account, configure it
@@ -128,6 +178,7 @@ like this:
     example domain with your actual domain.
   - Configure a mailer in `cluster.mailers` with your Mailgun API key.
 
+
 Postmark Setup
 ==============
 
@@ -143,7 +194,8 @@ discussion of the remote address whitelist used to verify that requests this
 endpoint receives are authentic requests originating from Postmark.
 
 
-= SendGrid Setup =
+SendGrid Setup
+==============
 
 To use SendGrid, you need a SendGrid account with access to the "Parse API" for
 inbound email. Provided you have such an account, configure it like this:
@@ -159,14 +211,16 @@ inbound email. Provided you have such an account, configure it like this:
   - If you get an error that the hostname "can't be located or verified", it
     means your MX record is either incorrectly configured or hasn't propagated
     yet.
-  - Set `metamta.reply-handler-domain` to `phabricator.example.com`"
+  - Set `metamta.reply-handler-domain` to `phabricator.example.com`
     (whatever you configured the MX record for).
 
 That's it! If everything is working properly you should be able to send email
 to `anything@phabricator.example.com` and it should appear in
 `bin/mail list-inbound` within a few seconds.
 
-= Local MTA: Installing Mailparse =
+
+Local MTA: Installing Mailparse
+===============================
 
 If you're going to run your own MTA, you need to install the PECL mailparse
 extension. In theory, you can do that with:
@@ -189,7 +243,8 @@ If you get a linker error like this:
 mailparse.so. This is not the default if you have individual files in
 `php.d/`.
 
-= Local MTA: Configuring Sendmail =
+Local MTA: Configuring Sendmail
+===============================
 
 Before you can configure Sendmail, you need to install Mailparse. See the
 section "Installing Mailparse" above.

src/docs/user/configuration/configuring_outbound_email.diviner

@@ -11,8 +11,8 @@ including a local mailer or various third-party services. Options include:
 
 | Send Mail With | Setup | Cost | Inbound | Notes |
 |---------|-------|------|---------|-------|
-| Mailgun | Easy | Cheap | Yes | Recommended |
 | Postmark | Easy | Cheap | Yes | Recommended |
+| Mailgun | Easy | Cheap | Yes | Recommended |
 | Amazon SES | Easy | Cheap | No | Recommended |
 | SendGrid | Medium | Cheap | Yes | Discouraged |
 | External SMTP | Medium | Varies | No | Gmail, etc. |
@@ -23,12 +23,11 @@ including a local mailer or various third-party services. Options include:
 See below for details on how to select and configure mail delivery for each
 mailer.
 
-Overall, Mailgun and SES are much easier to set up, and using one of them is
+Overall, Postmark and Mailgun are much easier to set up, and using one of them
-recommended. In particular, Mailgun will also let you set up inbound email
+is recommended. Both will also let you set up inbound email easily.
-easily.
 
-If you have some internal mail service you'd like to use you can also
+If you have some internal mail service you'd like to use you can also write a
-write a custom mailer, but this requires digging into the code.
+custom mailer, but this requires digging into the code.
 
 Phabricator sends mail in the background, so the daemons need to be running for
 it to be able to deliver mail. You should receive setup warnings if they are
@@ -39,14 +38,15 @@ not. For more information on using daemons, see
 Basics
 ======
 
-Regardless of how outbound email is delivered, you should configure these keys
+Before configuring outbound mail, you should first set up
-in your configuration:
+`metamta.default-address` in Configuration. This determines where mail is sent
+"From" by default.
 
-  - **metamta.default-address** determines where mail is sent "From" by
+If your domain is `example.org`, set this to something
-    default. If your domain is `example.org`, set this to something like
+like `noreply@example.org`.
-    `noreply@example.org`.
+
-  - **metamta.can-send-as-user** should be left as `false` in most cases,
+Ideally, this should be a valid, deliverable address that doesn't bounce if
-    but see the documentation for details.
+users accidentally send mail to it.
 
 
 Configuring Mailers
@@ -95,7 +95,7 @@ The `type` field can be used to select these third-party mailers:
 
   - `mailgun`: Use Mailgun.
   - `ses`: Use Amazon SES.
-  - `sendgrid`: Use Sendgrid.
+  - `sendgrid`: Use SendGrid.
   - `postmark`: Use Postmark.
 
 It also supports these local mailers:
@@ -104,12 +104,12 @@ It also supports these local mailers:
   - `smtp`: Connect directly to an SMTP server.
   - `test`: Internal mailer for testing. Does not send mail.
 
-You can also write your own mailer by extending
+You can also write your own mailer by extending `PhabricatorMailAdapter`.
-`PhabricatorMailAdapter`.
 
 The `media` field supports these values:
 
   - `email`: Configure this mailer for email.
+  - `sms`: Configure this mailer for SMS.
 
 Once you've selected a mailer, find the corresponding section below for
 instructions on configuring it.
@@ -149,22 +149,10 @@ For alternatives and more information on configuration, see
 @{article:Configuration User Guide: Advanced Configuration}
 
 
-Mailer: Mailgun
-===============
-
-Mailgun is a third-party email delivery service. You can learn more at
-<http://www.mailgun.com>. Mailgun is easy to configure and works well.
-
-To use this mailer, set `type` to `mailgun`, then configure these `options`:
-
-  - `api-key`: Required string. Your Mailgun API key.
-  - `domain`: Required string. Your Mailgun domain.
-
-
 Mailer: Postmark
 ================
 
-Postmark is a third-party email delivery serivice. You can learn more at
+Postmark is a third-party email delivery service. You can learn more at
 <https://www.postmarkapp.com/>.
 
 To use this mailer, set `type` to `postmark`, then configure these `options`:
@@ -191,6 +179,18 @@ The default address ranges were last updated in January 2019, and were
 documented at: <https://postmarkapp.com/support/article/800-ips-for-firewalls>
 
 
+Mailer: Mailgun
+===============
+
+Mailgun is a third-party email delivery service. You can learn more at
+<http://www.mailgun.com>. Mailgun is easy to configure and works well.
+
+To use this mailer, set `type` to `mailgun`, then configure these `options`:
+
+  - `api-key`: Required string. Your Mailgun API key.
+  - `domain`: Required string. Your Mailgun domain.
+
+
 Mailer: Amazon SES
 ==================
 
@@ -204,7 +204,7 @@ To use this mailer, set `type` to `ses`, then configure these `options`:
   - `endpoint`: Required string. Your Amazon SES endpoint.
 
 NOTE: Amazon SES **requires you to verify your "From" address**. Configure
-which "From" address to use by setting "`metamta.default-address`" in your
+which "From" address to use by setting `metamta.default-address` in your
 config, then follow the Amazon SES verification process to verify it. You
 won't be able to send email until you do this!
 
@@ -221,27 +221,25 @@ API. To use SMTP, configure Phabricator to use an `smtp` mailer.
 To use the REST API mailer, set `type` to `sendgrid`, then configure
 these `options`:
 
-  - `api-user`: Required string. Your SendGrid login name.
   - `api-key`: Required string. Your SendGrid API key.
 
-NOTE: Users have experienced a number of odd issues with SendGrid, compared to
+Older versions of the SendGrid API used different sets of credentials,
-fewer issues with other mailers. We discourage SendGrid unless you're already
+including an "API User". Make sure you're configuring your "API Key".
-using it.
 
 
 Mailer: Sendmail
 ================
 
-This requires a `sendmail` binary to be installed on
+This requires a `sendmail` binary to be installed on the system. Most MTAs
-the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your
+(e.g., sendmail, qmail, postfix) should do this, but your machine may not have
-machine may not have one installed by default. For install instructions, consult
+one installed by default. For install instructions, consult the documentation
-the documentation for your favorite MTA.
+for your favorite MTA.
 
 Since you'll be sending the mail yourself, you are subject to things like SPF
 rules, blackholes, and MTA configuration which are beyond the scope of this
 document. If you can already send outbound email from the command line or know
 how to configure it, this option is straightforward. If you have no idea how to
-do any of this, strongly consider using Mailgun or Amazon SES instead.
+do any of this, strongly consider using Postmark or Mailgun instead.
 
 To use this mailer, set `type` to `sendmail`. There are no `options` to
 configure.