Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_outbound_email.diviner
Show All 11 Lines | |||||
types of messages (like text messages). | types of messages (like text messages). | ||||
Phabricator can send outbound messages through multiple different mailers, | Phabricator can send outbound messages through multiple different mailers, | ||||
including a local mailer or various third-party services. Options include: | including a local mailer or various third-party services. Options include: | ||||
| Send Mail With | Setup | Cost | Inbound | Media | Notes | | | Send Mail With | Setup | Cost | Inbound | Media | Notes | | ||||
|----------------|-------|------|---------|-------|-------| | |----------------|-------|------|---------|-------|-------| | ||||
| Postmark | Easy | Cheap | Yes | Email | Recommended | | | Postmark | Easy | Cheap | Yes | Email | Recommended | | ||||
| Mailgun | Easy | Cheap | Yes | Email | Recommended | | |||||
| Amazon SES | Easy | Cheap | No | Email | | | | Amazon SES | Easy | Cheap | No | Email | | | ||||
| SendGrid | Medium | Cheap | Yes | Email | | | | SendGrid | Medium | Cheap | Yes | Email | | | ||||
| Twilio | Easy | Cheap | No | SMS | Recommended | | | Twilio | Easy | Cheap | No | SMS | Recommended | | ||||
| Amazon SNS | Easy | Cheap | No | SMS | Recommended | | | Amazon SNS | Easy | Cheap | No | SMS | Recommended | | ||||
| External SMTP | Medium | Varies | No | Email | Gmail, etc. | | | External SMTP | Medium | Varies | No | Email | Gmail, etc. | | ||||
| Local SMTP | Hard | Free | No | Email | sendmail, postfix, etc | | | Local SMTP | Hard | Free | No | Email | sendmail, postfix, etc | | ||||
| Custom | Hard | Free | No | All | Write a custom mailer. | | | Custom | Hard | Free | No | All | Write a custom mailer. | | ||||
| Drop in a Hole | Easy | Free | No | All | Drops mail in a deep, dark hole. | | | Drop in a Hole | Easy | Free | No | All | Drops mail in a deep, dark hole. | | ||||
| Mailgun | Easy | Cheap | Yes | Email | Discouraged | | |||||
See below for details on how to select and configure mail delivery for each | See below for details on how to select and configure mail delivery for each | ||||
mailer. | mailer. | ||||
For email, Postmark or Mailgun are recommended because they make it easy to | For email, Postmark is recommended because it makes it easy to set up inbound | ||||
set up inbound and outbound mail and have good track records in our production | and outbound mail and has a good track record in our production services. Other | ||||
services. Other services will also generally work well, but they may be more | services will also generally work well, but they may be more difficult to set | ||||
difficult to set up. | up. | ||||
For SMS, Twilio or SNS are recommended. They're also your only upstream | For SMS, Twilio or SNS are recommended. They're also your only upstream | ||||
options. | options. | ||||
If you have some internal mail or messaging service you'd like to use you can | 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. | 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 | Phabricator sends mail in the background, so the daemons need to be running for | ||||
Show All 37 Lines | |||||
can configure multiple mailers to provide greater availability in the event of | can configure multiple mailers to provide greater availability in the event of | ||||
a service disruption. | a service disruption. | ||||
A valid `cluster.mailers` configuration looks something like this: | A valid `cluster.mailers` configuration looks something like this: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
{ | { | ||||
"key": "mycompany-mailgun", | "key": "mycompany-postmark", | ||||
"type": "mailgun", | "type": "postmark", | ||||
"options": { | "options": { | ||||
"domain": "mycompany.com", | "domain": "mycompany.com", | ||||
"api-key": "..." | "api-key": "..." | ||||
} | } | ||||
}, | }, | ||||
... | ... | ||||
] | ] | ||||
``` | ``` | ||||
Show All 13 Lines | The supported keys for each mailer are: | ||||
- `media`: Optional list<string>. Some mailers support delivering multiple | - `media`: Optional list<string>. Some mailers support delivering multiple | ||||
types of messages (like Email and SMS). If you want to configure a mailer | types of messages (like Email and SMS). If you want to configure a mailer | ||||
to support only a subset of possible message types, list only those message | to support only a subset of possible message types, list only those message | ||||
types. Normally, you do not need to configure this. See below for a list | types. Normally, you do not need to configure this. See below for a list | ||||
of media types. | of media types. | ||||
The `type` field can be used to select these mailer services: | The `type` field can be used to select these mailer services: | ||||
- `mailgun`: Use Mailgun. | |||||
- `ses`: Use Amazon SES. | - `ses`: Use Amazon SES. | ||||
- `sendgrid`: Use SendGrid. | - `sendgrid`: Use SendGrid. | ||||
- `postmark`: Use Postmark. | - `postmark`: Use Postmark. | ||||
- `twilio`: Use Twilio. | - `twilio`: Use Twilio. | ||||
- `sns`: Use Amazon SNS. | - `sns`: Use Amazon SNS. | ||||
- `mailgun`: Use Mailgun. | |||||
It also supports these local mailers: | It also supports these local mailers: | ||||
- `sendmail`: Use the local `sendmail` binary. | - `sendmail`: Use the local `sendmail` binary. | ||||
- `smtp`: Connect directly to an SMTP server. | - `smtp`: Connect directly to an SMTP server. | ||||
- `test`: Internal mailer for testing. Does not send mail. | - `test`: Internal mailer for testing. Does not send mail. | ||||
You can also write your own mailer by extending `PhabricatorMailAdapter`. | You can also write your own mailer by extending `PhabricatorMailAdapter`. | ||||
▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines | |||||
The option accepts a list of CIDR ranges, like `1.2.3.4/16` (IPv4) or | The option accepts a list of CIDR ranges, like `1.2.3.4/16` (IPv4) or | ||||
`::ffff:0:0/96` (IPv6). The default ranges are: | `::ffff:0:0/96` (IPv6). The default ranges are: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
"50.31.156.6/32", | "50.31.156.6/32", | ||||
"50.31.156.77/32", | "50.31.156.77/32", | ||||
"18.217.206.57/32" | "18.217.206.57/32", | ||||
"3.134.147.250/32" | |||||
] | ] | ||||
``` | ``` | ||||
The default address ranges were last updated in January 2019, and were | The default address ranges were last updated in December 2021, and were | ||||
documented at: <https://postmarkapp.com/support/article/800-ips-for-firewalls> | documented at: <https://postmarkapp.com/support/article/800-ips-for-firewalls> | ||||
Mailer: Mailgun | Mailer: Mailgun | ||||
=============== | =============== | ||||
| Media | Email | | Media | Email | ||||
|---------| | |---------| | ||||
| Inbound | Yes | | Inbound | Yes | ||||
|---------| | |---------| | ||||
Use of Mailgun is discouraged because of concerns that they may not be a | |||||
trustworthy custodian of sensitive data. See <https://phurl.io/u/mailgun> for | |||||
discussion and context. | |||||
Mailgun is a third-party email delivery service. You can learn more at | Mailgun is a third-party email delivery service. You can learn more at | ||||
<https://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`: | To use this mailer, set `type` to `mailgun`, then configure these `options`: | ||||
- `api-key`: Required string. Your Mailgun API key. | - `api-key`: Required string. Your Mailgun API key. | ||||
- `domain`: Required string. Your Mailgun domain. | - `domain`: Required string. Your Mailgun domain. | ||||
- `api-hostname`: Optional string. Defaults to "api.mailgun.net". If your | - `api-hostname`: Optional string. Defaults to "api.mailgun.net". If your | ||||
▲ Show 20 Lines • Show All 103 Lines • ▼ Show 20 Lines | |||||
(e.g., sendmail, qmail, postfix) should install one for you, but your machine | (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 | may not have one installed by default. For install instructions, consult the | ||||
documentation for your favorite MTA. | documentation for your favorite MTA. | ||||
Since you'll be sending the mail yourself, you are subject to things like SPF | 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 | rules, blackholes, and MTA configuration which are beyond the scope of this | ||||
document. If you can already send outbound email from the command line or know | document. If you can already send outbound email from the command line or know | ||||
how to configure it, this option is straightforward. If you have no idea how to | how to configure it, this option is straightforward. If you have no idea how to | ||||
do any of this, strongly consider using Postmark or Mailgun instead. | do any of this, strongly consider using Postmark instead. | ||||
To use this mailer, set `type` to `sendmail`, then configure these `options`: | To use this mailer, set `type` to `sendmail`, then configure these `options`: | ||||
- `message-id`: Optional bool. Set to `false` if Phabricator will not be | - `message-id`: Optional bool. Set to `false` if Phabricator will not be | ||||
able to select a custom "Message-ID" header when sending mail via this | able to select a custom "Message-ID" header when sending mail via this | ||||
mailer. See "Message-ID Headers" below. | mailer. See "Message-ID Headers" below. | ||||
Mailer: SMTP | Mailer: SMTP | ||||
▲ Show 20 Lines • Show All 60 Lines • ▼ Show 20 Lines | |||||
at the moment) it will try the second mailer, and so on. | at the moment) it will try the second mailer, and so on. | ||||
If you want to load balance between multiple mailers instead of using one as | If you want to load balance between multiple mailers instead of using one as | ||||
a primary, you can set `priority`. Phabricator will start with mailers in the | a primary, you can set `priority`. Phabricator will start with mailers in the | ||||
highest priority group and go through them randomly, then fall back to the | highest priority group and go through them randomly, then fall back to the | ||||
next group. | next group. | ||||
For example, if you have two SMTP servers and you want to balance requests | For example, if you have two SMTP servers and you want to balance requests | ||||
between them and then fall back to Mailgun if both fail, configure priorities | between them and then fall back to Postmark if both fail, configure priorities | ||||
like this: | like this: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
{ | { | ||||
"key": "smtp-uswest", | "key": "smtp-uswest", | ||||
"type": "smtp", | "type": "smtp", | ||||
"priority": 300, | "priority": 300, | ||||
"options": "..." | "options": "..." | ||||
}, | }, | ||||
{ | { | ||||
"key": "smtp-useast", | "key": "smtp-useast", | ||||
"type": "smtp", | "type": "smtp", | ||||
"priority": 300, | "priority": 300, | ||||
"options": "..." | "options": "..." | ||||
}, | }, | ||||
{ | { | ||||
"key": "mailgun-fallback", | "key": "postmark-fallback", | ||||
"type": "mailgun", | "type": "postmark", | ||||
"options": "..." | "options": "..." | ||||
} | } | ||||
} | } | ||||
``` | ``` | ||||
Phabricator will start with servers in the highest priority group (the group | Phabricator will start with servers in the highest priority group (the group | ||||
with the **largest** `priority` number). In this example, the highest group is | with the **largest** `priority` number). In this example, the highest group is | ||||
`300`, which has the two SMTP servers. They'll be tried in random order first. | `300`, which has the two SMTP servers. They'll be tried in random order first. | ||||
If both fail, Phabricator will move on to the next priority group. In this | If both fail, Phabricator will move on to the next priority group. In this | ||||
example, there are no other priority groups. | example, there are no other priority groups. | ||||
If it still hasn't sent the mail, Phabricator will try servers which are not | If it still hasn't sent the mail, Phabricator will try servers which are not | ||||
in any priority group, in the configured order. In this example there is | in any priority group, in the configured order. In this example there is | ||||
only one such server, so it will try to send via Mailgun. | only one such server, so it will try to send via Postmark. | ||||
Message-ID Headers | Message-ID Headers | ||||
================== | ================== | ||||
Email has a "Message-ID" header which is important for threading messages | Email has a "Message-ID" header which is important for threading messages | ||||
correctly in mail clients. Normally, Phabricator is free to select its own | correctly in mail clients. Normally, Phabricator is free to select its own | ||||
"Message-ID" header values for mail it sends. | "Message-ID" header values for mail it sends. | ||||
▲ Show 20 Lines • Show All 51 Lines • Show Last 20 Lines |