Organize, update, and improve some documentation.

src/docs/configuration/configuring_outbound_email.diviner

@@ -0,0 +1,172 @@
+@title Configuring Outbound Email
+@group config
+
+Instructions for configuring Phabricator to send mail.
+
+= Overview =
+
+Phabricator can send outbound email via several different adapters:
+
+  - by running ##sendmail## on the local host with SMTP; or
+  - by using Amazon SES (Simple Email Service); or
+  - by using SendGrid's REST API; or
+  - via a custom adapter you write; or
+  - by dropping email into a hole and not delivering it.
+
+Of these, ##sendmail## is the default but requires some configuration. SES and
+SendGrid are easier, but cost money and have some limitations. Writing a custom
+solution requires digging into the code. See below for details on how to set up
+each method.
+
+Phabricator can also send outbound email in two ways:
+
+  - immediately, when messages are generated (default); or
+  - in the background, via a daemon.
+
+Sending mail in the background requires more configuration, but will greatly
+improve the performance of the application if your mail handler is slow. Note
+that Amazon SES commonly takes 1-2 seconds per email. If you use SES,
+**strongly consider** configuring the daemon. You should also configure the
+daemon if commenting on Revisions or Tasks feels slow, as it may significantly
+improve performance.
+
+= Basics =
+
+Regardless of how outbound email is delivered, you should configure these keys
+in your configuration file:
+
+  - **metamta.default-address** determines where mail is sent "From" by
+    default. If your domain is ##example.org##, set this to something like
+    "##noreply@example.org##".
+  - **metamta.domain** should be set to your domain, e.g. "##example.org##".
+  - **metamta.can-send-as-user** should be left as ##false## in most cases,
+    but see the documentation in ##default.conf.php## for details.
+
+= Configuring Mail Adapters =
+
+To choose how mail will be sent, change the **metamta.mail-adapter** key in
+your configuration. Possible values are:
+
+  - ##PhabricatorMailImplementationPHPMailerLiteAdapter##: default, uses
+    "sendmail", see "Adapter: Sendmail".
+  - ##PhabricatorMailImplementationAmazonSESAdapter##: use Amazon SES, see
+    "Adapter: Amazon SES".
+  - ##PhabricatorMailImplementationSendGridAdapter##: use SendGrid, see
+    "Adapter: SendGrid".
+  - ##Some Custom Class You Write##: use a custom adapter you write, see
+    "Adapter: Custom".
+  - ##PhabricatorMailImplementationTestAdapter##: this will
+    **completely disable** outbound mail. You can use this if you don't want to
+    send outbound mail, or want to skip this step for now and configure it
+    later.
+
+= Adapter: Sendmail =
+
+This is the default, and selected by choosing
+##PhabricatorMailImplementationPHPMailerLiteAdapter## as the value for
+**metamta.mail-adapter**. This requires a 'sendmail' binary to be installed on
+the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your
+machine may not have one installed by default. For install instructions, consult
+the documentation 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, consider using Amazon SES.
+
+= Adapter: Amazon SES =
+
+Amazon SES is Amazon's cloud email service. It is not free, but is easier to
+configure than sendmail and can simplify outbound email configuration. To use
+Amazon SES, you need to sign up for an account with Amazon at
+<http://aws.amazon.com/ses/>.
+
+To configure Phabricator to use Amazon SES, set these configuration keys:
+
+  - **metamta.mail-adapter**: set to
+    "PhabricatorMailImplementationAmazonSESAdapter".
+  - **amazon-ses.access-key**: set to your Amazon SES access key.
+  - **amazon-ses.secret-key**: set to your Amazon SES secret key.
+
+NOTE: Amazon SES **requires you to verify your "From" address**. Configure 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!
+
+NOTE: Amazon SES is slow to accept mail (often 1-2 seconds) and application
+performance will improve greatly if you configure outbound email to send in
+the background.
+
+= Adapter: SendGrid =
+
+SendGrid is an email delivery service like Amazon SES. You can learn more at
+<http://sendgrid.com/>. It is easy to configure, but not free.
+
+You can configure SendGrid in two ways: you can send via SMTP or via the REST
+API. To use SMTP, just configure ##sendmail## and leave Phabricator's setup
+with defaults. To use the REST API, follow the instructions in this section.
+
+To configure Phabricator to use SendGrid, set these configuration keys:
+
+  - **metamta.mail-adapter**: set to
+    "PhabricatorMailImplementationSendGridAdapter".
+  - **sendgrid.api-user**: set to your SendGrid login name.
+  - **sendgrid.api-key**: set to your SendGrid password.
+
+If you're logged into your SendGrid account, you may be able to find this
+information easily by visiting <http://sendgrid.com/developer>.
+
+= Adapter: Custom =
+
+You can provide a custom adapter by writing a concrete subclass of
+@{class:PhabricatorMailImplementationAdapter} and setting it as the
+**metamta.mail-adapter**.
+
+TODO: This needs to be better documented once extending Phabricator is better
+documented.
+
+= Adapter: Disable Outbound Mail =
+
+You can use the @{class:PhabricatorMailImplementationTestAdapter} to completely
+disable outbound mail, if you don't want to send mail or don't want to configure
+it yet. Just set **metamta.mail-adapter** to
+"PhabricatorMailImplementationTestAdapter".
+
+= Configuring the MetaMTA Daemon =
+
+Regardless of how you are sending outbound email, you can move the handoff to
+the MTA out of the main process and into a daemon. This will greatly improve
+application performance if your mailer is slow, like Amazon SES. In particular,
+commenting on Differential Revisions and Maniphest Tasks sends outbound email.
+
+To use the MetaMTA daemon:
+
+  - set **metamta.send-immediately** to ##false## in your configuration; and
+  - launch a ##metamta## daemon with ##phabricator/bin/phd launch metamta##.
+
+For more information on using daemons, see @{article:Managing Daemons with phd}.
+
+= Testing and Debugging Outbound Email =
+
+Phabricator has a mail log and test console at ##/mail/##, or click the
+**MetaMTA** link from the homepage. This console shows all the mail Phabricator
+has attempted to deliver, plus debugging and error information.
+
+You can use the "Send New Message" button to send mail using the current
+configuration. This can help test that your setup is correct.
+
+NOTE: when you send mail, "to" and "cc" must be valid users of the system, not
+arbitrary email addresses.
+
+You can monitor daemons using the Daemon Console (##/daemon/##, or click
+**Daemon Console** from the homepage).
+
+= Next Steps =
+
+Continue by:
+
+  - @{article:Configuring Inbound Email} so users can reply to email they
+  receive about revisions and tasks to interact with them; or
+  - learning about daemons with @{article:Managing Daemons with phd}; or
+  - returning to the @{article:Configuration Guide}.