Page MenuHomePhabricator
Differential D19973 Diff 47712 src/docs/user/configuration/configuring_inbound_email.diviner

Changeset View

Standalone View

View Options

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 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
amckinleyUnsubmitted
Not Done
Inline Actions

This is a little less awkward to parse than "!commands mail commands":

"via mail commands, like !subscribe or !close"

amckinley: This is a little less awkward to parse than "!commands mail commands": > "via 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.
amckinleyUnsubmitted
Not Done
Inline Actions

Maybe explicitly mention DNS in this step?

amckinley: Maybe explicitly mention DNS in this step?
- For handling replies, set `metamta.reply-handler-domain` in configuration.
amckinleyUnsubmitted
Not Done
Inline Actions

"in your configuration"

amckinley: "in your 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.
amckinleyUnsubmitted
Not Done
Inline Actions

This just subtracts hope. I'd skip it, especially since we already call out local MTA as being tricksy below.

amckinley: This just subtracts hope. I'd skip it, especially since we already call out local MTA as being…
There are a few approaches available: There are a few approaches available:
| 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 | Extremely Difficult | Free | Strongly discouraged! | | Local MTA | Extremely Difficult | Free | Strongly discouraged! |
The remainder of this document walks through configuring Phabricator to The remainder of this document walks through configuring Phabricator 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 Phabricator.
= Configuring Phabricator =
Configuring "Reply" Email
=========================
By default, Phabricator uses a `noreply@phabricator.example.com` email address 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
amckinleyUnsubmitted
Not Done
Inline Actions

"(e.g., the user taking the action)"

amckinley: "(e.g., the user taking the action)"
mail was generated by a user action. This means that users can reply (or 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 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 in Phabricator and users will not be able to take actions like claiming tasks or
requesting changes to revisions. requesting changes to revisions.
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 Phabricator
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, emails will use a `phabricator.example.com`. Once you set this key, emails will use a
'Reply-To' like `T123+273+af310f9220ad@phabricator.example.com`, which -- when 'Reply-To' like `T123+273+af310f9220ad@phabricator.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 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 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 Phabricator 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.
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
amckinleyUnsubmitted
Not Done
Inline Actions

"create"

amckinley: "create"
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 > {nav icon=home, name=Home >
name=Applications > Applications >
icon=cog, name=Settings} type=instructions, name="Select an Application" >
icon=cog, name=Configure}
Not all application support creating objects via email.
amckinleyUnsubmitted
Not Done
Inline Actions

"applications"

amckinley: "applications"
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 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 unique to the recipient and includes a hash of user information and a unique
object ID, so it can only be used to update that object and only be used to act object ID, so it can only be used to update that object and only be used to act
on behalf of the recipient. on behalf of the recipient.
However, if an address is leaked (which is fairly easy -- for instance, However, if an address is leaked (which is fairly easy -- for instance,
forwarding an email will leak a live reply address, or a user might take a forwarding an email will leak a live reply address, or a user might take a
Show All 23 Lines
NOTE: Phabricator does not currently attempt to verify "From" addresses because NOTE: Phabricator 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 Phabricator or not:
phabricator/ $ ./bin/mail list-inbound # List inbound messages. phabricator/ $ ./bin/mail list-inbound # List inbound messages.
phabricator/ $ ./bin/mail show-inbound # Show details about a message. phabricator/ $ ./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. phabricator/ $ ./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://phabricator.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://<phabricator.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. `phabricator.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://phabricator.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 `phabricator.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@phabricator.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:
$ sudo pecl install mailparse $ sudo pecl install mailparse
You may run into an error like "needs mbstring". If so, try: You may run into an error like "needs mbstring". If so, try:
$ sudo yum install php-mbstring # or equivalent $ sudo yum install php-mbstring # or equivalent
$ sudo pecl install -n mailparse $ sudo pecl install -n mailparse
If you get a linker error like this: If you get a linker error like this:
COUNTEREXAMPLE COUNTEREXAMPLE
PHP Warning: PHP Startup: Unable to load dynamic library PHP Warning: PHP Startup: Unable to load dynamic library
'/usr/lib64/php/modules/mailparse.so' - /usr/lib64/php/modules/mailparse.so: '/usr/lib64/php/modules/mailparse.so' - /usr/lib64/php/modules/mailparse.so:
undefined symbol: mbfl_name2no_encoding in Unknown on line 0 undefined symbol: mbfl_name2no_encoding in Unknown on line 0
...you need to edit your php.ini file so that mbstring.so is loaded **before** ...you need to edit your php.ini file so that mbstring.so is loaded **before**
mailparse.so. This is not the default if you have individual files in mailparse.so. This is not the default if you have individual files in
`php.d/`. `php.d/`.
= Local MTA: Configuring Sendmail = Local MTA: Configuring Sendmail
===============================
Before you can configure Sendmail, you need to install Mailparse. See the Before you can configure Sendmail, you need to install Mailparse. See the
section "Installing Mailparse" above. section "Installing Mailparse" above.
Sendmail is very difficult to configure. First, you need to configure it for Sendmail is very difficult to configure. First, you need to configure it for
your domain so that mail can be delivered correctly. In broad strokes, this your domain so that mail can be delivered correctly. In broad strokes, this
probably means something like this: probably means something like this:
Show All 31 Lines
Phabricator · Built by Phacility