mirror of
https://we.phorge.it/source/phorge.git
synced 2024-12-27 16:00:59 +01:00
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
This commit is contained in:
epriestley
parent
8e5d9c6f0e
commit
50abc87363
1 changed files with 116 additions and 28 deletions
|
|
@ -1,33 +1,45 @@
|
|||
@title Configuring Outbound Email
|
||||
@group config
|
||||
|
||||
Instructions for configuring Phabricator to send mail.
|
||||
Instructions for configuring Phabricator to send email and other types of
|
||||
messages, like text messages.
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
Phabricator can send outbound email through several different mail services,
|
||||
Phabricator sends outbound messages through "mailers". Most mailers send
|
||||
email and most messages are email messages, but mailers may also send other
|
||||
types of messages (like text messages).
|
||||
|
||||
Phabricator can send outbound messages through multiple different mailers,
|
||||
including a local mailer or various third-party services. Options include:
|
||||
|
||||
| Send Mail With | Setup | Cost | Inbound | Notes |
|
||||
|---------|-------|------|---------|-------|
|
||||
| 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. |
|
||||
| Local SMTP | Hard | Free | No | sendmail, postfix, etc |
|
||||
| Custom | Hard | Free | No | Write a custom mailer for some other service. |
|
||||
| Drop in a Hole | Easy | Free | No | Drops mail in a deep, dark hole. |
|
||||
| Send Mail With | Setup | Cost | Inbound | Media | Notes |
|
||||
|----------------|-------|------|---------|-------|-------|
|
||||
| Postmark | Easy | Cheap | Yes | Email | Recommended |
|
||||
| Mailgun | Easy | Cheap | Yes | Email | Recommended |
|
||||
| Amazon SES | Easy | Cheap | No | Email | |
|
||||
| SendGrid | Medium | Cheap | Yes | Email | |
|
||||
| Twilio | Easy | Cheap | No | SMS | Recommended |
|
||||
| Amazon SNS | Easy | Cheap | No | SMS | Recommended |
|
||||
| External SMTP | Medium | Varies | No | Email | Gmail, etc. |
|
||||
| Local SMTP | Hard | Free | No | Email | sendmail, postfix, etc |
|
||||
| Custom | Hard | Free | No | All | Write a custom mailer. |
|
||||
| Drop in a Hole | Easy | Free | No | All | Drops mail in a deep, dark hole. |
|
||||
|
||||
See below for details on how to select and configure mail delivery for each
|
||||
mailer.
|
||||
|
||||
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.
|
||||
For email, Postmark or Mailgun are recommended because they make it easy to
|
||||
set up inbound and outbound mail and have good track records in our production
|
||||
services. Other services will also generally work well, but they may be more
|
||||
difficult to set up.
|
||||
|
||||
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.
|
||||
For SMS, Twilio or SNS are recommended. They're also your only upstream
|
||||
options.
|
||||
|
||||
If you have some internal mail or messaging 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
|
||||
|
|
@ -91,13 +103,14 @@ The supported keys for each mailer are:
|
|||
types. Normally, you do not need to configure this. See below for a list
|
||||
of media types.
|
||||
|
||||
The `type` field can be used to select these third-party mailers:
|
||||
The `type` field can be used to select these mailer services:
|
||||
|
||||
- `mailgun`: Use Mailgun.
|
||||
- `ses`: Use Amazon SES.
|
||||
- `sendgrid`: Use SendGrid.
|
||||
- `postmark`: Use Postmark.
|
||||
- `sns`: Use Amazon SNS (only for sending SMS messages).
|
||||
- `twilio`: Use Twilio.
|
||||
- `sns`: Use Amazon SNS.
|
||||
|
||||
It also supports these local mailers:
|
||||
|
||||
|
|
@ -153,6 +166,12 @@ For alternatives and more information on configuration, see
|
|||
Mailer: Postmark
|
||||
================
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | Yes
|
||||
|---------|
|
||||
|
||||
|
||||
Postmark is a third-party email delivery service. You can learn more at
|
||||
<https://www.postmarkapp.com/>.
|
||||
|
||||
|
|
@ -183,8 +202,13 @@ documented at: <https://postmarkapp.com/support/article/800-ips-for-firewalls>
|
|||
Mailer: Mailgun
|
||||
===============
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | Yes
|
||||
|---------|
|
||||
|
||||
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.
|
||||
<https://www.mailgun.com>. Mailgun is easy to configure and works well.
|
||||
|
||||
To use this mailer, set `type` to `mailgun`, then configure these `options`:
|
||||
|
||||
|
|
@ -195,8 +219,13 @@ To use this mailer, set `type` to `mailgun`, then configure these `options`:
|
|||
Mailer: Amazon SES
|
||||
==================
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | No
|
||||
|---------|
|
||||
|
||||
Amazon SES is Amazon's cloud email service. You can learn more at
|
||||
<http://aws.amazon.com/ses/>.
|
||||
<https://aws.amazon.com/ses/>.
|
||||
|
||||
To use this mailer, set `type` to `ses`, then configure these `options`:
|
||||
|
||||
|
|
@ -209,21 +238,58 @@ 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!
|
||||
|
||||
Mailer: Twilio
|
||||
==================
|
||||
|
||||
| Media | SMS
|
||||
|---------|
|
||||
| Inbound | No
|
||||
|---------|
|
||||
|
||||
Twilio is a third-party notification service. You can learn more at
|
||||
<https://www.twilio.com/>.
|
||||
|
||||
|
||||
To use this mailer, set `type` to `twilio`, then configure these options:
|
||||
|
||||
- `account-sid`: Your Twilio Account SID.
|
||||
- `auth-token`: Your Twilio Auth Token.
|
||||
- `from-number`: Number to send text messages from, in E.164 format
|
||||
(like `+15551237890`).
|
||||
|
||||
Mailer: Amazon SNS
|
||||
==================
|
||||
|
||||
| Media | SMS
|
||||
|---------|
|
||||
| Inbound | No
|
||||
|---------|
|
||||
|
||||
|
||||
Amazon SNS is Amazon's cloud notification service. You can learn more at
|
||||
<http://aws.amazon.com/sns/>. Note that this mailer is only able to send
|
||||
<https://aws.amazon.com/sns/>. Note that this mailer is only able to send
|
||||
SMS messages, not emails.
|
||||
|
||||
To use this mailer, set `type` to `sns`, then configure the options similarly
|
||||
to the SES configuration above.
|
||||
To use this mailer, set `type` to `sns`, then configure these options:
|
||||
|
||||
- `access-key`: Required string. Your Amazon SNS access key.
|
||||
- `secret-key`: Required string. Your Amazon SNS secret key.
|
||||
- `endpoint`: Required string. Your Amazon SNS endpoint.
|
||||
- `region`: Required string. Your Amazon SNS region.
|
||||
|
||||
You can find the correct `region` value for your endpoint in the SNS
|
||||
documentation.
|
||||
|
||||
Mailer: SendGrid
|
||||
================
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | Yes
|
||||
|---------|
|
||||
|
||||
SendGrid is a third-party email delivery service. You can learn more at
|
||||
<http://sendgrid.com/>.
|
||||
<https://sendgrid.com/>.
|
||||
|
||||
You can configure SendGrid in two ways: you can send via SMTP or via the REST
|
||||
API. To use SMTP, configure Phabricator to use an `smtp` mailer.
|
||||
|
|
@ -240,10 +306,16 @@ including an "API User". Make sure you're configuring your "API Key".
|
|||
Mailer: Sendmail
|
||||
================
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | Requires Configuration
|
||||
|---------|
|
||||
|
||||
|
||||
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.
|
||||
(e.g., sendmail, qmail, postfix) should install one for you, 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
|
||||
|
|
@ -258,6 +330,11 @@ configure.
|
|||
Mailer: SMTP
|
||||
============
|
||||
|
||||
| Media | Email
|
||||
|---------|
|
||||
| Inbound | Requires Configuration
|
||||
|---------|
|
||||
|
||||
You can use this adapter to send mail via an external SMTP server, like Gmail.
|
||||
|
||||
To use this mailer, set `type` to `smtp`, then configure these `options`:
|
||||
|
|
@ -273,7 +350,15 @@ To use this mailer, set `type` to `smtp`, then configure these `options`:
|
|||
Disable Mail
|
||||
============
|
||||
|
||||
To disable mail, just don't configure any mailers.
|
||||
| Media | All
|
||||
|---------|
|
||||
| Inbound | No
|
||||
|---------|
|
||||
|
||||
|
||||
To disable mail, just don't configure any mailers. (You can safely ignore the
|
||||
setup warning reminding you to set up mailers if you don't plan to configure
|
||||
any.)
|
||||
|
||||
|
||||
Testing and Debugging Outbound Email
|
||||
|
|
@ -288,6 +373,9 @@ particular:
|
|||
|
||||
Run `bin/mail help <command>` for more help on using these commands.
|
||||
|
||||
By default, `bin/mail send-test` sends email messages, but you can use
|
||||
the `--type` flag to send different types of messages.
|
||||
|
||||
You can monitor daemons using the Daemon Console (`/daemon/`, or click
|
||||
**Daemon Console** from the homepage).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue