@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
Expand outbound mailer documentation to mention SMS and include Twilio
Summary: Depends on D20031. Ref T13222.
Test Plan: Read "carefully".
Reviewers: amckinley
Reviewed By: amckinley
Maniphest Tasks: T13222
Differential Revision: https://secure.phabricator.com/D20032
+116
-28
+116
-28
src/docs/user/configuration/configuring_outbound_email.diviner
+116
-28
src/docs/user/configuration/configuring_outbound_email.diviner
···
1
1
@title Configuring Outbound Email
2
2
@group config
3
3
4
-
Instructions for configuring Phabricator to send mail.
4
+
Instructions for configuring Phabricator to send email and other types of
5
+
messages, like text messages.
5
6
6
7
Overview
7
8
========
8
9
9
-
Phabricator can send outbound email through several different mail services,
10
+
Phabricator sends outbound messages through "mailers". Most mailers send
11
+
email and most messages are email messages, but mailers may also send other
12
+
types of messages (like text messages).
13
+
14
+
Phabricator can send outbound messages through multiple different mailers,
10
15
including a local mailer or various third-party services. Options include:
11
16
12
-
| Send Mail With | Setup | Cost | Inbound | Notes |
13
-
|---------|-------|------|---------|-------|
14
-
| Postmark | Easy | Cheap | Yes | Recommended |
15
-
| Mailgun | Easy | Cheap | Yes | Recommended |
16
-
| Amazon SES | Easy | Cheap | No | Recommended |
17
-
| SendGrid | Medium | Cheap | Yes | Discouraged |
18
-
| External SMTP | Medium | Varies | No | Gmail, etc. |
19
-
| Local SMTP | Hard | Free | No | sendmail, postfix, etc |
20
-
| Custom | Hard | Free | No | Write a custom mailer for some other service. |
21
-
| Drop in a Hole | Easy | Free | No | Drops mail in a deep, dark hole. |
17
+
| Send Mail With | Setup | Cost | Inbound | Media | Notes |
18
+
|----------------|-------|------|---------|-------|-------|
19
+
| Postmark | Easy | Cheap | Yes | Email | Recommended |
20
+
| Mailgun | Easy | Cheap | Yes | Email | Recommended |
21
+
| Amazon SES | Easy | Cheap | No | Email | |
22
+
| SendGrid | Medium | Cheap | Yes | Email | |
23
+
| Twilio | Easy | Cheap | No | SMS | Recommended |
24
+
| Amazon SNS | Easy | Cheap | No | SMS | Recommended |
25
+
| External SMTP | Medium | Varies | No | Email | Gmail, etc. |
26
+
| Local SMTP | Hard | Free | No | Email | sendmail, postfix, etc |
27
+
| Custom | Hard | Free | No | All | Write a custom mailer. |
28
+
| Drop in a Hole | Easy | Free | No | All | Drops mail in a deep, dark hole. |
22
29
23
30
See below for details on how to select and configure mail delivery for each
24
31
mailer.
25
32
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.
33
+
For email, Postmark or Mailgun are recommended because they make it easy to
34
+
set up inbound and outbound mail and have good track records in our production
35
+
services. Other services will also generally work well, but they may be more
36
+
difficult to set up.
28
37
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.
38
+
For SMS, Twilio or SNS are recommended. They're also your only upstream
39
+
options.
40
+
41
+
If you have some internal mail or messaging service you'd like to use you can
42
+
also write a custom mailer, but this requires digging into the code.
31
43
32
44
Phabricator sends mail in the background, so the daemons need to be running for
33
45
it to be able to deliver mail. You should receive setup warnings if they are
···
91
103
types. Normally, you do not need to configure this. See below for a list
92
104
of media types.
93
105
94
-
The `type` field can be used to select these third-party mailers:
106
+
The `type` field can be used to select these mailer services:
95
107
96
108
- `mailgun`: Use Mailgun.
97
109
- `ses`: Use Amazon SES.
98
110
- `sendgrid`: Use SendGrid.
99
111
- `postmark`: Use Postmark.
100
-
- `sns`: Use Amazon SNS (only for sending SMS messages).
112
+
- `twilio`: Use Twilio.
113
+
- `sns`: Use Amazon SNS.
101
114
102
115
It also supports these local mailers:
103
116
···
153
166
Mailer: Postmark
154
167
================
155
168
169
+
| Media | Email
170
+
|---------|
171
+
| Inbound | Yes
172
+
|---------|
173
+
174
+
156
175
Postmark is a third-party email delivery service. You can learn more at
157
176
<https://www.postmarkapp.com/>.
158
177
···
183
202
Mailer: Mailgun
184
203
===============
185
204
205
+
| Media | Email
206
+
|---------|
207
+
| Inbound | Yes
208
+
|---------|
209
+
186
210
Mailgun is a third-party email delivery service. You can learn more at
187
-
<http://www.mailgun.com>. Mailgun is easy to configure and works well.
211
+
<https://www.mailgun.com>. Mailgun is easy to configure and works well.
188
212
189
213
To use this mailer, set `type` to `mailgun`, then configure these `options`:
190
214
···
195
219
Mailer: Amazon SES
196
220
==================
197
221
222
+
| Media | Email
223
+
|---------|
224
+
| Inbound | No
225
+
|---------|
226
+
198
227
Amazon SES is Amazon's cloud email service. You can learn more at
199
-
<http://aws.amazon.com/ses/>.
228
+
<https://aws.amazon.com/ses/>.
200
229
201
230
To use this mailer, set `type` to `ses`, then configure these `options`:
202
231
···
209
238
config, then follow the Amazon SES verification process to verify it. You
210
239
won't be able to send email until you do this!
211
240
241
+
Mailer: Twilio
242
+
==================
243
+
244
+
| Media | SMS
245
+
|---------|
246
+
| Inbound | No
247
+
|---------|
248
+
249
+
Twilio is a third-party notification service. You can learn more at
250
+
<https://www.twilio.com/>.
251
+
252
+
253
+
To use this mailer, set `type` to `twilio`, then configure these options:
254
+
255
+
- `account-sid`: Your Twilio Account SID.
256
+
- `auth-token`: Your Twilio Auth Token.
257
+
- `from-number`: Number to send text messages from, in E.164 format
258
+
(like `+15551237890`).
259
+
212
260
Mailer: Amazon SNS
213
261
==================
214
262
263
+
| Media | SMS
264
+
|---------|
265
+
| Inbound | No
266
+
|---------|
267
+
268
+
215
269
Amazon SNS is Amazon's cloud notification service. You can learn more at
216
-
<http://aws.amazon.com/sns/>. Note that this mailer is only able to send
270
+
<https://aws.amazon.com/sns/>. Note that this mailer is only able to send
217
271
SMS messages, not emails.
218
272
219
-
To use this mailer, set `type` to `sns`, then configure the options similarly
220
-
to the SES configuration above.
273
+
To use this mailer, set `type` to `sns`, then configure these options:
274
+
275
+
- `access-key`: Required string. Your Amazon SNS access key.
276
+
- `secret-key`: Required string. Your Amazon SNS secret key.
277
+
- `endpoint`: Required string. Your Amazon SNS endpoint.
278
+
- `region`: Required string. Your Amazon SNS region.
279
+
280
+
You can find the correct `region` value for your endpoint in the SNS
281
+
documentation.
221
282
222
283
Mailer: SendGrid
223
284
================
224
285
286
+
| Media | Email
287
+
|---------|
288
+
| Inbound | Yes
289
+
|---------|
290
+
225
291
SendGrid is a third-party email delivery service. You can learn more at
226
-
<http://sendgrid.com/>.
292
+
<https://sendgrid.com/>.
227
293
228
294
You can configure SendGrid in two ways: you can send via SMTP or via the REST
229
295
API. To use SMTP, configure Phabricator to use an `smtp` mailer.
···
240
306
Mailer: Sendmail
241
307
================
242
308
309
+
| Media | Email
310
+
|---------|
311
+
| Inbound | Requires Configuration
312
+
|---------|
313
+
314
+
243
315
This requires a `sendmail` binary to be installed on the system. Most MTAs
244
-
(e.g., sendmail, qmail, postfix) should do this, but your machine may not have
245
-
one installed by default. For install instructions, consult the documentation
246
-
for your favorite MTA.
316
+
(e.g., sendmail, qmail, postfix) should install one for you, but your machine
317
+
may not have one installed by default. For install instructions, consult the
318
+
documentation for your favorite MTA.
247
319
248
320
Since you'll be sending the mail yourself, you are subject to things like SPF
249
321
rules, blackholes, and MTA configuration which are beyond the scope of this
···
258
330
Mailer: SMTP
259
331
============
260
332
333
+
| Media | Email
334
+
|---------|
335
+
| Inbound | Requires Configuration
336
+
|---------|
337
+
261
338
You can use this adapter to send mail via an external SMTP server, like Gmail.
262
339
263
340
To use this mailer, set `type` to `smtp`, then configure these `options`:
···
273
350
Disable Mail
274
351
============
275
352
276
-
To disable mail, just don't configure any mailers.
353
+
| Media | All
354
+
|---------|
355
+
| Inbound | No
356
+
|---------|
357
+
358
+
359
+
To disable mail, just don't configure any mailers. (You can safely ignore the
360
+
setup warning reminding you to set up mailers if you don't plan to configure
361
+
any.)
277
362
278
363
279
364
Testing and Debugging Outbound Email
···
287
372
phabricator/ $ ./bin/mail send-test # Send test messages.
288
373
289
374
Run `bin/mail help <command>` for more help on using these commands.
375
+
376
+
By default, `bin/mail send-test` sends email messages, but you can use
377
+
the `--type` flag to send different types of messages.
290
378
291
379
You can monitor daemons using the Daemon Console (`/daemon/`, or click
292
380
**Daemon Console** from the homepage).