mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-10 00:42:41 +01:00
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
This commit is contained in:
parent
c5f446defb
commit
bd077bfcb7
2 changed files with 114 additions and 61 deletions
|
@ -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 @@ 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
|
||||
'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 @@ 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
|
||||
`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}
|
||||
|
||||
= 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.
|
||||
|
|
|
@ -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
|
||||
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 @@ not. For more information on using daemons, see
|
|||
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 @@ 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
|
||||
`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 @@ 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
|
||||
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.
|
||||
|
|
Loading…
Reference in a new issue