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

Wordsmith inbound mail documentation more thoroughly

Browse source 
Summary: See D19973. Fix a couple typos and try to make some sections more clear / less scary.

Test Plan: Read text.

Reviewers: amckinley

Reviewed By: amckinley

Differential Revision: https://secure.phabricator.com/D19986
This commit is contained in:
epriestley 2019-01-16 14:27:34 -08:00
parent bd077bfcb7
commit 0a0afa489a
1 changed files with 26 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -15,34 +15,37 @@ 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.
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
`!close` to close a task or `!priority` to change task priority.)
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 replies, set `metamta.reply-handler-domain` 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
==========
Configuration Overview
======================
Inbound mail can be extremely difficult to configure correctly. This is doubly
true if you use a local MTA.
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
you use a third-party mail service which can submit mail to Phabricator via
webhooks.
There are a few approaches available:
Some available approaches for delivering mail to Phabricator are:
| Receive Mail With | Setup | Cost | Notes |
|--------|-------|------|-------|
| Mailgun | Easy | Cheap | Recommended |
| Postmark | Easy | Cheap | Recommended |
| SendGrid | Easy | Cheap | |
| Local MTA | Extremely Difficult | Free | Strongly discouraged! |
| Local MTA | Difficult | Free | Discouraged |
The remainder of this document walks through configuring Phabricator to
receive mail, and then configuring your chosen transport to deliver mail
@ -53,18 +56,20 @@ 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
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
requesting changes to revisions.
as the "From" address when it sends mail. The exact address it uses can be
configured with `metamta.default-address`.
When a user takes an action that generates mail, Phabricator sets the
"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
be recorded in Phabricator; and users will not be able to use email commands
to take actions or make edits.
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
domain you configure according to the instructions below, e.g.
`phabricator.example.com`. Once you set this key, emails will use a
'Reply-To' like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
`phabricator.example.com`. Once you set this key, email will use a
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
configured correctly, according to the instructions below -- will parse incoming
email and allow users to interact with Differential revisions, Maniphest tasks,
etc. over email.
@ -82,8 +87,8 @@ 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.
email. For example, you could configure `bugs@phabricator.example.com` to
create a Maniphest task out of any email which is sent to it.
You can find application email settings for each application at:
@ -92,7 +97,7 @@ Applications >
type=instructions, name="Select an Application" >
icon=cog, name=Configure}
Not all application support creating objects via email.
Not all applications 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