Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_inbound_email.diviner
@title Configuring Inbound Email | @title Configuring Inbound Email | ||||
@group config | @group config | ||||
This document contains instructions for configuring inbound email, so users | This document contains instructions for configuring inbound email, so users | ||||
may interact with some Phabricator applications via email. | may interact with some Phorge applications via email. | ||||
Preamble | Preamble | ||||
======== | ======== | ||||
Phabricator can process inbound mail in two general ways: | Phorge can process inbound mail in two general ways: | ||||
**Handling Replies**: When users reply to email notifications about changes, | **Handling Replies**: When users reply to email notifications about changes, | ||||
Phabricator can turn email into comments on the relevant discussion thread. | Phorge can turn email into comments on the relevant discussion thread. | ||||
**Creating Objects**: You can configure an address like `bugs@yourcompany.com` | **Creating Objects**: You can configure an address like `bugs@yourcompany.com` | ||||
to create new objects (like tasks) when users send email. | to create new objects (like tasks) when users send email. | ||||
In either case, users can interact with objects via mail commands to apply a | In either case, users can interact with objects via mail commands to apply a | ||||
broader set of changes to objects beyond commenting. (For example, you can use | broader set of changes to objects beyond commenting. (For example, you can use | ||||
`!close` to close a task or `!priority` to change task priority.) | `!close` to close a task or `!priority` to change task priority.) | ||||
To configure inbound mail, you will generally: | To configure inbound mail, you will generally: | ||||
- Configure some mail domain to submit mail to Phabricator for processing. | - Configure some mail domain to submit mail to Phorge for processing. | ||||
- For handling replies, set `metamta.reply-handler-domain` in your | - For handling replies, set `metamta.reply-handler-domain` in your | ||||
configuration. | configuration. | ||||
- For handling email that creates objects, configure inbound addresses in the | - For handling email that creates objects, configure inbound addresses in the | ||||
relevant application. | relevant application. | ||||
See below for details on each of these steps. | See below for details on each of these steps. | ||||
Configuration Overview | Configuration Overview | ||||
====================== | ====================== | ||||
Usually, the most challenging part of configuring inbound mail is getting mail | Usually, the most challenging part of configuring inbound mail is getting mail | ||||
delivered to Phabricator for processing. This step can be made much easier if | delivered to Phorge for processing. This step can be made much easier if | ||||
you use a third-party mail service which can submit mail to Phabricator via | you use a third-party mail service which can submit mail to Phorge via | ||||
webhooks. | webhooks. | ||||
Some available approaches for delivering mail to Phabricator are: | Some available approaches for delivering mail to Phorge are: | ||||
| Receive Mail With | Setup | Cost | Notes | | | Receive Mail With | Setup | Cost | Notes | | ||||
|--------|-------|------|-------| | |--------|-------|------|-------| | ||||
| Mailgun | Easy | Cheap | Recommended | | | Mailgun | Easy | Cheap | Recommended | | ||||
| Postmark | Easy | Cheap | Recommended | | | Postmark | Easy | Cheap | Recommended | | ||||
| SendGrid | Easy | Cheap | | | | SendGrid | Easy | Cheap | | | ||||
| Local MTA | Difficult | Free | Discouraged | | | Local MTA | Difficult | Free | Discouraged | | ||||
The remainder of this document walks through configuring Phabricator to | The remainder of this document walks through configuring Phorge to | ||||
receive mail, and then configuring your chosen transport to deliver mail | receive mail, and then configuring your chosen transport to deliver mail | ||||
to Phabricator. | to Phorge. | ||||
Configuring "Reply" Email | Configuring "Reply" Email | ||||
========================= | ========================= | ||||
By default, Phabricator uses a `noreply@phabricator.example.com` email address | By default, Phorge uses a `noreply@phorge.example.com` email address | ||||
as the "From" address when it sends mail. The exact address it uses can be | as the "From" address when it sends mail. The exact address it uses can be | ||||
configured with `metamta.default-address`. | configured with `metamta.default-address`. | ||||
When a user takes an action that generates mail, Phabricator sets the | When a user takes an action that generates mail, Phorge sets the | ||||
"Reply-To" addresss for the mail to that user's name and address. This means | "Reply-To" addresss for the mail to that user's name and address. This means | ||||
that users can reply to email to discuss changes, but: the conversation won't | that users can reply to email to discuss changes, but: the conversation won't | ||||
be recorded in Phabricator; and users will not be able to use email commands | be recorded in Phorge; and users will not be able to use email commands | ||||
to take actions or make edits. | to take actions or make edits. | ||||
To change this behavior so that users can interact with objects in Phabricator | To change this behavior so that users can interact with objects in Phorge | ||||
over email, change the configuration key `metamta.reply-handler-domain` to some | over email, change the configuration key `metamta.reply-handler-domain` to some | ||||
domain you configure according to the instructions below, e.g. | domain you configure according to the instructions below, e.g. | ||||
`phabricator.example.com`. Once you set this key, email will use a | `phorge.example.com`. Once you set this key, email will use a | ||||
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when | "Reply-To" like `T123+273+af310f9220ad@phorge.example.com`, which -- when | ||||
configured correctly, according to the instructions below -- will parse incoming | configured correctly, according to the instructions below -- will parse incoming | ||||
email and allow users to interact with Differential revisions, Maniphest tasks, | email and allow users to interact with Differential revisions, Maniphest tasks, | ||||
etc. over email. | etc. over email. | ||||
If you don't want Phabricator to take up an entire domain (or subdomain) you | If you don't want Phorge to take up an entire domain (or subdomain) you | ||||
can configure a general prefix so you can use a single mailbox to receive mail | 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 | 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 Phorge will prepend this to the "Reply-To" | ||||
mail address. This works because everything up to the first (optional) '+' | 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. | after is essentially ignored. | ||||
Configuring "Create" Email | Configuring "Create" Email | ||||
========================== | ========================== | ||||
You can set up application email addresses to allow users to create objects via | 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 | email. For example, you could configure `bugs@phorge.example.com` to | ||||
create a Maniphest task out of any email which is sent to it. | create a Maniphest task out of any email which is sent to it. | ||||
You can find application email settings for each application at: | You can find application email settings for each application at: | ||||
{nav icon=home, name=Home > | {nav icon=home, name=Home > | ||||
Applications > | Applications > | ||||
type=instructions, name="Select an Application" > | type=instructions, name="Select an Application" > | ||||
icon=cog, name=Configure} | icon=cog, name=Configure} | ||||
Not all applications support creating objects via email. | Not all applications support creating objects via email. | ||||
In some applications, including Maniphest, you can also configure Herald rules | In some applications, including Maniphest, you can also configure Herald rules | ||||
with the `[ Content source ]` and/or `[ Receiving email address ]` fields to | with the `[ Content source ]` and/or `[ Receiving email address ]` fields to | ||||
route or handle objects based on which address mail was sent 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 | 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 | Phorge by following the instructions below. Phorge will let you add | ||||
any address as an application address, but can only process mail which is | any address as an application address, but can only process mail which is | ||||
actually delivered to it. | actually delivered to it. | ||||
Security | Security | ||||
======== | ======== | ||||
The email reply channel is "somewhat" authenticated. Each reply-to address is | The email reply channel is "somewhat" authenticated. Each reply-to address is | ||||
Show All 9 Lines | |||||
revisions) are not permitted over email. | revisions) are not permitted over email. | ||||
This implementation is an attempt to balance utility and security, but makes | This implementation is an attempt to balance utility and security, but makes | ||||
some sacrifices on both sides to achieve it because of the difficulty of | some sacrifices on both sides to achieve it because of the difficulty of | ||||
authenticating senders in the general case (e.g., where you are an open source | authenticating senders in the general case (e.g., where you are an open source | ||||
project and need to interact with users whose email accounts you have no control | project and need to interact with users whose email accounts you have no control | ||||
over). | over). | ||||
You can also set `metamta.public-replies`, which will change how Phabricator | You can also set `metamta.public-replies`, which will change how Phorge | ||||
delivers email. Instead of sending each recipient a unique mail with a personal | delivers email. Instead of sending each recipient a unique mail with a personal | ||||
reply-to address, it will send a single email to everyone with a public reply-to | reply-to address, it will send a single email to everyone with a public reply-to | ||||
address. This decreases security because anyone who can spoof a "From" address | address. This decreases security because anyone who can spoof a "From" address | ||||
can act as another user, but increases convenience if you use mailing lists and, | can act as another user, but increases convenience if you use mailing lists and, | ||||
practically, is a reasonable setting for many installs. The reply-to address | practically, is a reasonable setting for many installs. The reply-to address | ||||
will still contain a hash unique to the object it represents, so users who have | will still contain a hash unique to the object it represents, so users who have | ||||
not received an email about an object can not blindly interact with it. | not received an email about an object can not blindly interact with it. | ||||
If you enable application email addresses, those addresses also use the weaker | If you enable application email addresses, those addresses also use the weaker | ||||
"From" authentication mechanism. | "From" authentication mechanism. | ||||
NOTE: Phabricator does not currently attempt to verify "From" addresses because | NOTE: Phorge does not currently attempt to verify "From" addresses because | ||||
this is technically complex, seems unreasonably difficult in the general case, | this is technically complex, seems unreasonably difficult in the general case, | ||||
and no installs have had a need for it yet. If you have a specific case where a | and no installs have had a need for it yet. If you have a specific case where a | ||||
reasonable mechanism exists to provide sender verification (e.g., DKIM | reasonable mechanism exists to provide sender verification (e.g., DKIM | ||||
signatures are sufficient to authenticate the sender under your configuration, | 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 | or you are willing to require all users to sign their email), file a feature | ||||
request. | 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 | 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: | help you determine if mail is being delivered to Phorge or not: | ||||
phabricator/ $ ./bin/mail list-inbound # List inbound messages. | phorge/ $ ./bin/mail list-inbound # List inbound messages. | ||||
phabricator/ $ ./bin/mail show-inbound # Show details about a message. | phorge/ $ ./bin/mail show-inbound # Show details about a message. | ||||
You can also test receiving mail, but note that this just simulates receiving | You can also test receiving mail, but note that this just simulates receiving | ||||
the mail and doesn't send any information over the network. It is | the mail and doesn't send any information over the network. It is | ||||
primarily aimed at developing email handlers: it will still work properly | primarily aimed at developing email handlers: it will still work properly | ||||
if your inbound email configuration is incorrect or even disabled. | if your inbound email configuration is incorrect or even disabled. | ||||
phabricator/ $ ./bin/mail receive-test # Receive test message. | phorge/ $ ./bin/mail receive-test # Receive test message. | ||||
Run `bin/mail help <command>` for detailed help on using these commands. | 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 | 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 | <http://www.mailgun.com>. Provided you have such an account, configure it | ||||
like this: | like this: | ||||
- Configure a mail domain according to Mailgun's instructions. | - Configure a mail domain according to Mailgun's instructions. | ||||
- Add a Mailgun route with a `catch_all()` rule which takes the action | - Add a Mailgun route with a `catch_all()` rule which takes the action | ||||
`forward("https://phabricator.example.com/mail/mailgun/")`. Replace the | `forward("https://phorge.example.com/mail/mailgun/")`. Replace the | ||||
example domain with your actual domain. | example domain with your actual domain. | ||||
- Configure a mailer in `cluster.mailers` with your Mailgun API key. | - Configure a mailer in `cluster.mailers` with your Mailgun API key. | ||||
Postmark Setup | Postmark Setup | ||||
============== | ============== | ||||
To process inbound mail from Postmark, configure this URI as your inbound | To process inbound mail from Postmark, configure this URI as your inbound | ||||
webhook URI in the Postmark control panel: | webhook URI in the Postmark control panel: | ||||
``` | ``` | ||||
https://<phabricator.yourdomain.com>/mail/postmark/ | https://<phorge.yourdomain.com>/mail/postmark/ | ||||
``` | ``` | ||||
See also the Postmark section in @{article:Configuring Outbound Email} for | See also the Postmark section in @{article:Configuring Outbound Email} for | ||||
discussion of the remote address whitelist used to verify that requests this | discussion of the remote address whitelist used to verify that requests this | ||||
endpoint receives are authentic requests originating from Postmark. | 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 | 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: | inbound email. Provided you have such an account, configure it like this: | ||||
- Configure an MX record according to SendGrid's instructions, i.e. add | - Configure an MX record according to SendGrid's instructions, i.e. add | ||||
`phabricator.example.com MX 10 mx.sendgrid.net.` or similar. | `phorge.example.com MX 10 mx.sendgrid.net.` or similar. | ||||
- Go to the "Parse Incoming Emails" page on SendGrid | - Go to the "Parse Incoming Emails" page on SendGrid | ||||
(<http://sendgrid.com/developer/reply>) and add the domain as the | (<http://sendgrid.com/developer/reply>) and add the domain as the | ||||
"Hostname". | "Hostname". | ||||
- Add the URL `https://phabricator.example.com/mail/sendgrid/` as the "Url", | - Add the URL `https://phorge.example.com/mail/sendgrid/` as the "Url", | ||||
using your domain (and HTTP instead of HTTPS if you are not configured with | using your domain (and HTTP instead of HTTPS if you are not configured with | ||||
SSL). | SSL). | ||||
- If you get an error that the hostname "can't be located or verified", it | - 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 | means your MX record is either incorrectly configured or hasn't propagated | ||||
yet. | yet. | ||||
- Set `metamta.reply-handler-domain` to `phabricator.example.com` | - Set `metamta.reply-handler-domain` to `phorge.example.com` | ||||
(whatever you configured the MX record for). | (whatever you configured the MX record for). | ||||
That's it! If everything is working properly you should be able to send email | 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 | to `anything@phorge.example.com` and it should appear in | ||||
`bin/mail list-inbound` within a few seconds. | `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 | If you're going to run your own MTA, you need to install the PECL mailparse | ||||
extension. In theory, you can do that with: | extension. In theory, you can do that with: | ||||
Show All 27 Lines | |||||
probably means something like this: | probably means something like this: | ||||
- add an MX record; | - add an MX record; | ||||
- make sendmail listen on external interfaces; | - make sendmail listen on external interfaces; | ||||
- open up port 25 if necessary (e.g., in your EC2 security policy); | - open up port 25 if necessary (e.g., in your EC2 security policy); | ||||
- add your host to /etc/mail/local-host-names; and | - add your host to /etc/mail/local-host-names; and | ||||
- restart sendmail. | - restart sendmail. | ||||
Now, you can actually configure sendmail to deliver to Phabricator. In | Now, you can actually configure sendmail to deliver to Phorge. In | ||||
`/etc/aliases`, add an entry like this: | `/etc/aliases`, add an entry like this: | ||||
phabricator: "| /path/to/phabricator/scripts/mail/mail_handler.php" | phorge: "| /path/to/phorge/scripts/mail/mail_handler.php" | ||||
If you use the `PHABRICATOR_ENV` environmental variable to select a | If you use the `PHABRICATOR_ENV` environmental variable to select a | ||||
configuration, you can pass the value to the script as an argument: | configuration, you can pass the value to the script as an argument: | ||||
.../path/to/mail_handler.php <ENV> | .../path/to/mail_handler.php <ENV> | ||||
This is an advanced feature which is rarely used. Most installs should run | This is an advanced feature which is rarely used. Most installs should run | ||||
without an argument. | without an argument. | ||||
After making this change, run `sudo newaliases`. Now you likely need to symlink | After making this change, run `sudo newaliases`. Now you likely need to symlink | ||||
this script into `/etc/smrsh/`: | this script into `/etc/smrsh/`: | ||||
sudo ln -s /path/to/phabricator/scripts/mail/mail_handler.php /etc/smrsh/ | sudo ln -s /path/to/phorge/scripts/mail/mail_handler.php /etc/smrsh/ | ||||
Finally, edit `/etc/mail/virtusertable` and add an entry like this: | Finally, edit `/etc/mail/virtusertable` and add an entry like this: | ||||
@yourdomain.com phabricator@localhost | @yourdomain.com phorge@localhost | ||||
That will forward all mail to @yourdomain.com to the Phabricator processing | That will forward all mail to @yourdomain.com to the Phorge processing | ||||
script. Run `sudo /etc/mail/make` or similar and then restart sendmail with | script. Run `sudo /etc/mail/make` or similar and then restart sendmail with | ||||
`sudo /etc/init.d/sendmail restart`. | `sudo /etc/init.d/sendmail restart`. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0