revi-archive/phorge-phorge
1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-26 16:52:41 +01:00
Code Issues Releases Wiki Activity

Update inbound and outbound email documentation

Browse source 
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:
epriestley 2019-01-14 15:19:29 -08:00
parent c5f446defb
commit bd077bfcb7
2 changed files with 114 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
src/docs/user/configuration/configuring_inbound_email.diviner
View file

@ -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.

76
src/docs/user/configuration/configuring_outbound_email.diviner
View file

@ -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.