@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
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
+114
-61
+77
-22
src/docs/user/configuration/configuring_inbound_email.diviner
+77
-22
src/docs/user/configuration/configuring_inbound_email.diviner
···
4
4
This document contains instructions for configuring inbound email, so users
5
5
may interact with some Phabricator applications via email.
6
6
7
-
= Preamble =
7
+
Preamble
8
+
========
9
+
10
+
Phabricator can process inbound mail in two general ways:
11
+
12
+
**Handling Replies**: When users reply to email notifications about changes,
13
+
Phabricator can turn email into comments on the relevant discussion thread.
14
+
15
+
**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
16
+
to create new objects (like tasks) when users send email.
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.
8
21
9
-
This can be extremely difficult to configure correctly. This is doubly true if
10
-
you use a local MTA.
22
+
To configure inbound mail, you will generally:
23
+
24
+
- Configure some mail domain to submit mail to Phabricator for processing.
25
+
- For handling replies, set `metamta.reply-handler-domain` in configuration.
26
+
- For handling email that creates objects, configure inbound addresses in the
27
+
relevant application.
28
+
29
+
See below for details on each of these steps.
30
+
31
+
32
+
Approaches
33
+
==========
34
+
35
+
Inbound mail can be extremely difficult to configure correctly. This is doubly
36
+
true if you use a local MTA.
11
37
12
38
There are a few approaches available:
13
39
···
22
48
receive mail, and then configuring your chosen transport to deliver mail
23
49
to Phabricator.
24
50
25
-
= Configuring Phabricator =
51
+
52
+
Configuring "Reply" Email
53
+
=========================
26
54
27
55
By default, Phabricator uses a `noreply@phabricator.example.com` email address
28
-
as the 'From' (configurable with `metamta.default-address`) and sets
29
-
'Reply-To' to the user generating the email (e.g., by making a comment), if the
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
30
58
mail was generated by a user action. This means that users can reply (or
31
59
reply-all) to email to discuss changes, but the conversation won't be recorded
32
60
in Phabricator and users will not be able to take actions like claiming tasks or
···
44
72
If you don't want Phabricator to take up an entire domain (or subdomain) you
45
73
can configure a general prefix so you can use a single mailbox to receive mail
46
74
on. To make use of this set `metamta.single-reply-handler-prefix` to the
47
-
prefix of your choice, and Phabricator will prepend this to the 'Reply-To'
75
+
prefix of your choice, and Phabricator will prepend this to the "Reply-To"
48
76
mail address. This works because everything up to the first (optional) '+'
49
-
character in an email-address is considered the receiver, and everything
77
+
character in an email address is considered the receiver, and everything
50
78
after is essentially ignored.
51
79
52
-
You can also set up application email addresses to allow users to create
53
-
application objects via email. For example, you could configure
54
-
`bugs@phabricator.example.com` to create a Maniphest task out of any email
55
-
which is sent to it. To do this, see application settings for a given
56
-
application at
80
+
81
+
Configuring "Create" Email
82
+
==========================
83
+
84
+
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.
87
+
88
+
You can find application email settings for each application at:
57
89
58
90
{nav icon=home, name=Home >
59
-
name=Applications >
60
-
icon=cog, name=Settings}
91
+
Applications >
92
+
type=instructions, name="Select an Application" >
93
+
icon=cog, name=Configure}
94
+
95
+
Not all application support creating objects via email.
96
+
97
+
In some applications, including Maniphest, you can also configure Herald rules
98
+
with the `[ Content source ]` and/or `[ Receiving email address ]` fields to
99
+
route or handle objects based on which address mail was sent to.
100
+
101
+
You'll also need to configure the actual mail domain to submit mail to
102
+
Phabricator by following the instructions below. Phabricator will let you add
103
+
any address as an application address, but can only process mail which is
104
+
actually delivered to it.
105
+
61
106
62
-
= Security =
107
+
Security
108
+
========
63
109
64
110
The email reply channel is "somewhat" authenticated. Each reply-to address is
65
111
unique to the recipient and includes a hash of user information and a unique
···
99
145
or you are willing to require all users to sign their email), file a feature
100
146
request.
101
147
102
-
= Testing and Debugging Inbound Email =
148
+
149
+
Testing and Debugging Inbound Email
150
+
===================================
103
151
104
152
You can use the `bin/mail` utility to test and review inbound mail. This can
105
153
help you determine if mail is being delivered to Phabricator or not:
···
116
164
117
165
Run `bin/mail help <command>` for detailed help on using these commands.
118
166
119
-
= Mailgun Setup =
167
+
168
+
Mailgun Setup
169
+
=============
120
170
121
171
To use Mailgun, you need a Mailgun account. You can sign up at
122
172
<http://www.mailgun.com>. Provided you have such an account, configure it
···
127
177
`forward("https://phabricator.example.com/mail/mailgun/")`. Replace the
128
178
example domain with your actual domain.
129
179
- Configure a mailer in `cluster.mailers` with your Mailgun API key.
180
+
130
181
131
182
Postmark Setup
132
183
==============
···
143
194
endpoint receives are authentic requests originating from Postmark.
144
195
145
196
146
-
= SendGrid Setup =
197
+
SendGrid Setup
198
+
==============
147
199
148
200
To use SendGrid, you need a SendGrid account with access to the "Parse API" for
149
201
inbound email. Provided you have such an account, configure it like this:
···
159
211
- If you get an error that the hostname "can't be located or verified", it
160
212
means your MX record is either incorrectly configured or hasn't propagated
161
213
yet.
162
-
- Set `metamta.reply-handler-domain` to `phabricator.example.com`"
214
+
- Set `metamta.reply-handler-domain` to `phabricator.example.com`
163
215
(whatever you configured the MX record for).
164
216
165
217
That's it! If everything is working properly you should be able to send email
166
218
to `anything@phabricator.example.com` and it should appear in
167
219
`bin/mail list-inbound` within a few seconds.
168
220
169
-
= Local MTA: Installing Mailparse =
221
+
222
+
Local MTA: Installing Mailparse
223
+
===============================
170
224
171
225
If you're going to run your own MTA, you need to install the PECL mailparse
172
226
extension. In theory, you can do that with:
···
189
243
mailparse.so. This is not the default if you have individual files in
190
244
`php.d/`.
191
245
192
-
= Local MTA: Configuring Sendmail =
246
+
Local MTA: Configuring Sendmail
247
+
===============================
193
248
194
249
Before you can configure Sendmail, you need to install Mailparse. See the
195
250
section "Installing Mailparse" above.
+37
-39
src/docs/user/configuration/configuring_outbound_email.diviner
+37
-39
src/docs/user/configuration/configuring_outbound_email.diviner
···
11
11
12
12
| Send Mail With | Setup | Cost | Inbound | Notes |
13
13
|---------|-------|------|---------|-------|
14
-
| Mailgun | Easy | Cheap | Yes | Recommended |
15
14
| Postmark | Easy | Cheap | Yes | Recommended |
15
+
| Mailgun | Easy | Cheap | Yes | Recommended |
16
16
| Amazon SES | Easy | Cheap | No | Recommended |
17
17
| SendGrid | Medium | Cheap | Yes | Discouraged |
18
18
| External SMTP | Medium | Varies | No | Gmail, etc. |
···
23
23
See below for details on how to select and configure mail delivery for each
24
24
mailer.
25
25
26
-
Overall, Mailgun and SES are much easier to set up, and using one of them is
27
-
recommended. In particular, Mailgun will also let you set up inbound email
28
-
easily.
26
+
Overall, Postmark and Mailgun are much easier to set up, and using one of them
27
+
is recommended. Both will also let you set up inbound email easily.
29
28
30
-
If you have some internal mail service you'd like to use you can also
31
-
write a custom mailer, but this requires digging into the code.
29
+
If you have some internal mail service you'd like to use you can also write a
30
+
custom mailer, but this requires digging into the code.
32
31
33
32
Phabricator sends mail in the background, so the daemons need to be running for
34
33
it to be able to deliver mail. You should receive setup warnings if they are
···
39
38
Basics
40
39
======
41
40
42
-
Regardless of how outbound email is delivered, you should configure these keys
43
-
in your configuration:
41
+
Before configuring outbound mail, you should first set up
42
+
`metamta.default-address` in Configuration. This determines where mail is sent
43
+
"From" by default.
44
44
45
-
- **metamta.default-address** determines where mail is sent "From" by
46
-
default. If your domain is `example.org`, set this to something like
47
-
`noreply@example.org`.
48
-
- **metamta.can-send-as-user** should be left as `false` in most cases,
49
-
but see the documentation for details.
45
+
If your domain is `example.org`, set this to something
46
+
like `noreply@example.org`.
47
+
48
+
Ideally, this should be a valid, deliverable address that doesn't bounce if
49
+
users accidentally send mail to it.
50
50
51
51
52
52
Configuring Mailers
···
95
95
96
96
- `mailgun`: Use Mailgun.
97
97
- `ses`: Use Amazon SES.
98
-
- `sendgrid`: Use Sendgrid.
98
+
- `sendgrid`: Use SendGrid.
99
99
- `postmark`: Use Postmark.
100
100
101
101
It also supports these local mailers:
···
104
104
- `smtp`: Connect directly to an SMTP server.
105
105
- `test`: Internal mailer for testing. Does not send mail.
106
106
107
-
You can also write your own mailer by extending
108
-
`PhabricatorMailAdapter`.
107
+
You can also write your own mailer by extending `PhabricatorMailAdapter`.
109
108
110
109
The `media` field supports these values:
111
110
112
111
- `email`: Configure this mailer for email.
112
+
- `sms`: Configure this mailer for SMS.
113
113
114
114
Once you've selected a mailer, find the corresponding section below for
115
115
instructions on configuring it.
···
149
149
@{article:Configuration User Guide: Advanced Configuration}
150
150
151
151
152
-
Mailer: Mailgun
153
-
===============
154
-
155
-
Mailgun is a third-party email delivery service. You can learn more at
156
-
<http://www.mailgun.com>. Mailgun is easy to configure and works well.
157
-
158
-
To use this mailer, set `type` to `mailgun`, then configure these `options`:
159
-
160
-
- `api-key`: Required string. Your Mailgun API key.
161
-
- `domain`: Required string. Your Mailgun domain.
162
-
163
-
164
152
Mailer: Postmark
165
153
================
166
154
167
-
Postmark is a third-party email delivery serivice. You can learn more at
155
+
Postmark is a third-party email delivery service. You can learn more at
168
156
<https://www.postmarkapp.com/>.
169
157
170
158
To use this mailer, set `type` to `postmark`, then configure these `options`:
···
191
179
documented at: <https://postmarkapp.com/support/article/800-ips-for-firewalls>
192
180
193
181
182
+
Mailer: Mailgun
183
+
===============
184
+
185
+
Mailgun is a third-party email delivery service. You can learn more at
186
+
<http://www.mailgun.com>. Mailgun is easy to configure and works well.
187
+
188
+
To use this mailer, set `type` to `mailgun`, then configure these `options`:
189
+
190
+
- `api-key`: Required string. Your Mailgun API key.
191
+
- `domain`: Required string. Your Mailgun domain.
192
+
193
+
194
194
Mailer: Amazon SES
195
195
==================
196
196
···
204
204
- `endpoint`: Required string. Your Amazon SES endpoint.
205
205
206
206
NOTE: Amazon SES **requires you to verify your "From" address**. Configure
207
-
which "From" address to use by setting "`metamta.default-address`" in your
207
+
which "From" address to use by setting `metamta.default-address` in your
208
208
config, then follow the Amazon SES verification process to verify it. You
209
209
won't be able to send email until you do this!
210
210
···
221
221
To use the REST API mailer, set `type` to `sendgrid`, then configure
222
222
these `options`:
223
223
224
-
- `api-user`: Required string. Your SendGrid login name.
225
224
- `api-key`: Required string. Your SendGrid API key.
226
225
227
-
NOTE: Users have experienced a number of odd issues with SendGrid, compared to
228
-
fewer issues with other mailers. We discourage SendGrid unless you're already
229
-
using it.
226
+
Older versions of the SendGrid API used different sets of credentials,
227
+
including an "API User". Make sure you're configuring your "API Key".
230
228
231
229
232
230
Mailer: Sendmail
233
231
================
234
232
235
-
This requires a `sendmail` binary to be installed on
236
-
the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your
237
-
machine may not have one installed by default. For install instructions, consult
238
-
the documentation for your favorite MTA.
233
+
This requires a `sendmail` binary to be installed on the system. Most MTAs
234
+
(e.g., sendmail, qmail, postfix) should do this, but your machine may not have
235
+
one installed by default. For install instructions, consult the documentation
236
+
for your favorite MTA.
239
237
240
238
Since you'll be sending the mail yourself, you are subject to things like SPF
241
239
rules, blackholes, and MTA configuration which are beyond the scope of this
242
240
document. If you can already send outbound email from the command line or know
243
241
how to configure it, this option is straightforward. If you have no idea how to
244
-
do any of this, strongly consider using Mailgun or Amazon SES instead.
242
+
do any of this, strongly consider using Postmark or Mailgun instead.
245
243
246
244
To use this mailer, set `type` to `sendmail`. There are no `options` to
247
245
configure.