diff --git a/src/docs/user/configuration/configuring_inbound_email.diviner b/src/docs/user/configuration/configuring_inbound_email.diviner --- a/src/docs/user/configuration/configuring_inbound_email.diviner +++ b/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 -you use a local MTA. +Phabricator can process inbound mail in two general ways: + +**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 @@ 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 -'Reply-To' to the user generating the email (e.g., by making a comment), if the +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 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 @@ 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 -`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 + +Configuring "Create" Email +========================== + +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 > -icon=cog, name=Settings} +Applications > +type=instructions, name="Select an Application" > +icon=cog, name=Configure} + +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 = +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 @@ 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 @@ Run `bin/mail help ` for detailed help on using these commands. -= Mailgun Setup = + +Mailgun Setup +============= To use Mailgun, you need a Mailgun account. You can sign up at . Provided you have such an account, configure it @@ -128,6 +178,7 @@ example domain with your actual domain. - Configure a mailer in `cluster.mailers` with your Mailgun API key. + Postmark Setup ============== @@ -143,7 +194,8 @@ 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 @@ - 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 @@ 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. diff --git a/src/docs/user/configuration/configuring_outbound_email.diviner b/src/docs/user/configuration/configuring_outbound_email.diviner --- a/src/docs/user/configuration/configuring_outbound_email.diviner +++ b/src/docs/user/configuration/configuring_outbound_email.diviner @@ -11,8 +11,8 @@ | 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 @@ 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 -recommended. In particular, Mailgun will also let you set up inbound email -easily. +Overall, Postmark and Mailgun are much easier to set up, and using one of them +is recommended. Both will also let you set up inbound email easily. -If you have some internal mail service you'd like to use you can also -write a custom mailer, but this requires digging into the code. +If you have some internal mail service you'd like to use you can also write a +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 @@ Basics ====== -Regardless of how outbound email is delivered, you should configure these keys -in your configuration: +Before configuring outbound mail, you should first set up +`metamta.default-address` in Configuration. This determines where mail is sent +"From" by default. - - **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.can-send-as-user** should be left as `false` in most cases, - but see the documentation for details. +If your domain is `example.org`, set this to something +like `noreply@example.org`. + +Ideally, this should be a valid, deliverable address that doesn't bounce if +users accidentally send mail to it. Configuring Mailers @@ -95,7 +95,7 @@ - `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 @@ - `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 -`PhabricatorMailAdapter`. +You can also write your own mailer by extending `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 @@ @{article:Configuration User Guide: Advanced Configuration} -Mailer: Mailgun -=============== - -Mailgun is a third-party email delivery service. You can learn more at -. 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 . To use this mailer, set `type` to `postmark`, then configure these `options`: @@ -191,6 +179,18 @@ documented at: +Mailer: Mailgun +=============== + +Mailgun is a third-party email delivery service. You can learn more at +. 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 @@ - `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 @@ 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 -fewer issues with other mailers. We discourage SendGrid unless you're already -using it. +Older versions of the SendGrid API used different sets of credentials, +including an "API User". Make sure you're configuring your "API Key". Mailer: Sendmail ================ -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. +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, 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.