@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Wordsmith inbound mail documentation more thoroughly
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
+26
-21
+26
-21
src/docs/user/configuration/configuring_inbound_email.diviner
+26
-21
src/docs/user/configuration/configuring_inbound_email.diviner
···
15
15
**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
16
16
to create new objects (like tasks) when users send email.
17
17
18
-
In either case, users can interact with objects via `!commands` mail commands
19
-
to apply a broader set of changes to objects (like adding subscribers, closing
20
-
tasks, or changing priorities) beyond simply commenting.
18
+
In either case, users can interact with objects via mail commands to apply a
19
+
broader set of changes to objects beyond commenting. (For example, you can use
20
+
`!close` to close a task or `!priority` to change task priority.)
21
21
22
22
To configure inbound mail, you will generally:
23
23
24
24
- Configure some mail domain to submit mail to Phabricator for processing.
25
-
- For handling replies, set `metamta.reply-handler-domain` in configuration.
25
+
- For handling replies, set `metamta.reply-handler-domain` in your
26
+
configuration.
26
27
- For handling email that creates objects, configure inbound addresses in the
27
28
relevant application.
28
29
29
30
See below for details on each of these steps.
30
31
31
32
32
-
Approaches
33
-
==========
33
+
Configuration Overview
34
+
======================
34
35
35
-
Inbound mail can be extremely difficult to configure correctly. This is doubly
36
-
true if you use a local MTA.
36
+
Usually, the most challenging part of configuring inbound mail is getting mail
37
+
delivered to Phabricator for processing. This step can be made much easier if
38
+
you use a third-party mail service which can submit mail to Phabricator via
39
+
webhooks.
37
40
38
-
There are a few approaches available:
41
+
Some available approaches for delivering mail to Phabricator are:
39
42
40
43
| Receive Mail With | Setup | Cost | Notes |
41
44
|--------|-------|------|-------|
42
45
| Mailgun | Easy | Cheap | Recommended |
43
46
| Postmark | Easy | Cheap | Recommended |
44
47
| SendGrid | Easy | Cheap | |
45
-
| Local MTA | Extremely Difficult | Free | Strongly discouraged! |
48
+
| Local MTA | Difficult | Free | Discouraged |
46
49
47
50
The remainder of this document walks through configuring Phabricator to
48
51
receive mail, and then configuring your chosen transport to deliver mail
···
53
56
=========================
54
57
55
58
By default, Phabricator uses a `noreply@phabricator.example.com` email address
56
-
as the "From" (configurable with `metamta.default-address`) and sets
57
-
"Reply-To" to the user generating the email (e.g., by making a comment), if the
58
-
mail was generated by a user action. This means that users can reply (or
59
-
reply-all) to email to discuss changes, but the conversation won't be recorded
60
-
in Phabricator and users will not be able to take actions like claiming tasks or
61
-
requesting changes to revisions.
59
+
as the "From" address when it sends mail. The exact address it uses can be
60
+
configured with `metamta.default-address`.
61
+
62
+
When a user takes an action that generates mail, Phabricator sets the
63
+
"Reply-To" addresss for the mail to that user's name and address. This means
64
+
that users can reply to email to discuss changes, but: the conversation won't
65
+
be recorded in Phabricator; and users will not be able to use email commands
66
+
to take actions or make edits.
62
67
63
68
To change this behavior so that users can interact with objects in Phabricator
64
69
over email, change the configuration key `metamta.reply-handler-domain` to some
65
70
domain you configure according to the instructions below, e.g.
66
-
`phabricator.example.com`. Once you set this key, emails will use a
67
-
'Reply-To' like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
71
+
`phabricator.example.com`. Once you set this key, email will use a
72
+
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
68
73
configured correctly, according to the instructions below -- will parse incoming
69
74
email and allow users to interact with Differential revisions, Maniphest tasks,
70
75
etc. over email.
···
82
87
==========================
83
88
84
89
You can set up application email addresses to allow users to create objects via
85
-
email. For example, you could configure `bugs@phabricator.example.com` to creat
86
-
a Maniphest task out of any email which is sent to it.
90
+
email. For example, you could configure `bugs@phabricator.example.com` to
91
+
create a Maniphest task out of any email which is sent to it.
87
92
88
93
You can find application email settings for each application at:
89
94
···
92
97
type=instructions, name="Select an Application" >
93
98
icon=cog, name=Configure}
94
99
95
-
Not all application support creating objects via email.
100
+
Not all applications support creating objects via email.
96
101
97
102
In some applications, including Maniphest, you can also configure Herald rules
98
103
with the `[ Content source ]` and/or `[ Receiving email address ]` fields to