Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_outbound_email.diviner
@title Configuring Outbound Email | @title Configuring Outbound Email | ||||
@group config | @group config | ||||
Instructions for configuring Phabricator to send email and other types of | Instructions for configuring Phorge to send email and other types of | ||||
messages, like text messages. | messages, like text messages. | ||||
Overview | Overview | ||||
======== | ======== | ||||
Phabricator sends outbound messages through "mailers". Most mailers send | Phorge sends outbound messages through "mailers". Most mailers send | ||||
email and most messages are email messages, but mailers may also send other | email and most messages are email messages, but mailers may also send other | ||||
types of messages (like text messages). | types of messages (like text messages). | ||||
Phabricator can send outbound messages through multiple different mailers, | Phorge 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 | | | 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 | | | ||||
Show All 13 Lines | |||||
difficult to set up. | difficult to set 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 | Phorge 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 | it to be able to deliver mail. You should receive setup warnings if they are | ||||
not. For more information on using daemons, see | not. For more information on using daemons, see | ||||
@{article:Managing Daemons with phd}. | @{article:Managing Daemons with phd}. | ||||
Outbound "From" and "To" Addresses | Outbound "From" and "To" Addresses | ||||
================================== | ================================== | ||||
When Phabricator sends outbound mail, it must select some "From" address to | When Phorge sends outbound mail, it must select some "From" address to | ||||
send mail from, since mailers require this. | send mail from, since mailers require this. | ||||
When mail only has "CC" recipients, Phabricator generates a dummy "To" address, | When mail only has "CC" recipients, Phorge generates a dummy "To" address, | ||||
since some mailers require this and some users write mail rules that depend | since some mailers require this and some users write mail rules that depend | ||||
on whether they appear in the "To" or "CC" line. | on whether they appear in the "To" or "CC" line. | ||||
In both cases, the address should ideally correspond to a valid, deliverable | In both cases, the address should ideally correspond to a valid, deliverable | ||||
mailbox that accepts the mail and then simply discards it. If the address is | mailbox that accepts the mail and then simply discards it. If the address is | ||||
not valid, some outbound mail will bounce, and users will receive bounces when | not valid, some outbound mail will bounce, and users will receive bounces when | ||||
they "Reply All" even if the other recipients for the message are valid. In | they "Reply All" even if the other recipients for the message are valid. In | ||||
contrast, if the address is a real user address, that user will receive a lot | contrast, if the address is a real user address, that user will receive a lot | ||||
of mail they probably don't want. | of mail they probably don't want. | ||||
If you plan to configure //inbound// mail later, you usually don't need to do | If you plan to configure //inbound// mail later, you usually don't need to do | ||||
anything. Phabricator will automatically create a `noreply@` mailbox which | anything. Phorge will automatically create a `noreply@` mailbox which | ||||
works the right way (accepts and discards all mail it receives) and | works the right way (accepts and discards all mail it receives) and | ||||
automatically use it when generating addresses. | automatically use it when generating addresses. | ||||
If you don't plan to configure inbound mail, you may need to configure an | If you don't plan to configure inbound mail, you may need to configure an | ||||
address for Phabricator to use. You can do this by setting | address for Phorge to use. You can do this by setting | ||||
`metamta.default-address`. | `metamta.default-address`. | ||||
Configuring Mailers | Configuring Mailers | ||||
=================== | =================== | ||||
Configure one or more mailers by listing them in the the `cluster.mailers` | Configure one or more mailers by listing them in the the `cluster.mailers` | ||||
configuration option. Most installs only need to configure one mailer, but you | configuration option. Most installs only need to configure one mailer, but you | ||||
▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines | The `type` field can be used to select these mailer services: | ||||
- `sns`: Use Amazon SNS. | - `sns`: Use Amazon SNS. | ||||
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 `PhorgeMailAdapter`. | ||||
The `media` field supports these values: | The `media` field supports these values: | ||||
- `email`: Configure this mailer for email. | - `email`: Configure this mailer for email. | ||||
- `sms`: Configure this mailer for SMS. | - `sms`: Configure this mailer for SMS. | ||||
Once you've selected a mailer, find the corresponding section below for | Once you've selected a mailer, find the corresponding section below for | ||||
instructions on configuring it. | instructions on configuring it. | ||||
Show All 21 Lines | [ | ||||
"type": "test" | "type": "test" | ||||
} | } | ||||
] | ] | ||||
``` | ``` | ||||
Then set the value like this: | Then set the value like this: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/config set --stdin cluster.mailers < mailers.json | phorge/ $ ./bin/config set --stdin cluster.mailers < mailers.json | ||||
``` | ``` | ||||
For alternatives and more information on configuration, see | For alternatives and more information on configuration, see | ||||
@{article:Configuration User Guide: Advanced Configuration} | @{article:Configuration User Guide: Advanced Configuration} | ||||
Mailer: Postmark | Mailer: Postmark | ||||
================ | ================ | ||||
▲ Show 20 Lines • Show All 124 Lines • ▼ Show 20 Lines | |||||
|---------| | |---------| | ||||
| Inbound | Yes | | Inbound | Yes | ||||
|---------| | |---------| | ||||
SendGrid is a third-party email delivery service. You can learn more at | SendGrid is a third-party email delivery service. You can learn more at | ||||
<https://sendgrid.com/>. | <https://sendgrid.com/>. | ||||
You can configure SendGrid in two ways: you can send via SMTP or via the REST | 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. | API. To use SMTP, configure Phorge to use an `smtp` mailer. | ||||
To use the REST API mailer, set `type` to `sendgrid`, then configure | To use the REST API mailer, set `type` to `sendgrid`, then configure | ||||
these `options`: | these `options`: | ||||
- `api-key`: Required string. Your SendGrid API key. | - `api-key`: Required string. Your SendGrid API key. | ||||
Older versions of the SendGrid API used different sets of credentials, | Older versions of the SendGrid API used different sets of credentials, | ||||
including an "API User". Make sure you're configuring your "API Key". | including an "API User". Make sure you're configuring your "API Key". | ||||
Show All 16 Lines | |||||
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 or Mailgun 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 Phorge 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 | ||||
============ | ============ | ||||
| Media | Email | | Media | Email | ||||
|---------| | |---------| | ||||
| Inbound | Requires Configuration | | Inbound | Requires Configuration | ||||
|---------| | |---------| | ||||
You can use this adapter to send mail via an external SMTP server, like Gmail. | 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`: | To use this mailer, set `type` to `smtp`, then configure these `options`: | ||||
- `host`: Required string. The hostname of your SMTP server. | - `host`: Required string. The hostname of your SMTP server. | ||||
- `port`: Optional int. The port to connect to on your SMTP server. | - `port`: Optional int. The port to connect to on your SMTP server. | ||||
- `user`: Optional string. Username used for authentication. | - `user`: Optional string. Username used for authentication. | ||||
- `password`: Optional string. Password for authentication. | - `password`: Optional string. Password for authentication. | ||||
- `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use | - `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use | ||||
`ssl` for Gmail. | `ssl` for Gmail. | ||||
- `message-id`: Optional bool. Set to `false` if Phabricator will not be | - `message-id`: Optional bool. Set to `false` if Phorge 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. | ||||
Disable Mail | Disable Mail | ||||
============ | ============ | ||||
| Media | All | | Media | All | ||||
|---------| | |---------| | ||||
| Inbound | No | | Inbound | No | ||||
|---------| | |---------| | ||||
To disable mail, just don't configure any mailers. (You can safely ignore the | 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 | setup warning reminding you to set up mailers if you don't plan to configure | ||||
any.) | any.) | ||||
Testing and Debugging Outbound Email | Testing and Debugging Outbound Email | ||||
==================================== | ==================================== | ||||
You can use the `bin/mail` utility to test, debug, and examine outbound mail. In | You can use the `bin/mail` utility to test, debug, and examine outbound mail. In | ||||
particular: | particular: | ||||
phabricator/ $ ./bin/mail list-outbound # List outbound mail. | phorge/ $ ./bin/mail list-outbound # List outbound mail. | ||||
phabricator/ $ ./bin/mail show-outbound # Show details about messages. | phorge/ $ ./bin/mail show-outbound # Show details about messages. | ||||
phabricator/ $ ./bin/mail send-test # Send test messages. | phorge/ $ ./bin/mail send-test # Send test messages. | ||||
Run `bin/mail help <command>` for more help on using these commands. | 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 | By default, `bin/mail send-test` sends email messages, but you can use | ||||
the `--type` flag to send different types of messages. | the `--type` flag to send different types of messages. | ||||
You can monitor daemons using the Daemon Console (`/daemon/`, or click | You can monitor daemons using the Daemon Console (`/daemon/`, or click | ||||
**Daemon Console** from the homepage). | **Daemon Console** from the homepage). | ||||
Priorities | Priorities | ||||
========== | ========== | ||||
By default, Phabricator will try each mailer in order: it will try the first | By default, Phorge will try each mailer in order: it will try the first | ||||
mailer first. If that fails (for example, because the service is not available | mailer first. If that fails (for example, because the service is not available | ||||
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`. Phorge 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 Mailgun if both fail, configure priorities | ||||
like this: | like this: | ||||
```lang=json | ```lang=json | ||||
Show All 13 Lines | [ | ||||
{ | { | ||||
"key": "mailgun-fallback", | "key": "mailgun-fallback", | ||||
"type": "mailgun", | "type": "mailgun", | ||||
"options": "..." | "options": "..." | ||||
} | } | ||||
} | } | ||||
``` | ``` | ||||
Phabricator will start with servers in the highest priority group (the group | Phorge 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, Phorge 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, Phorge 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 Mailgun. | ||||
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, Phorge is free to select its own | ||||
"Message-ID" header values for mail it sends. | "Message-ID" header values for mail it sends. | ||||
However, some mailers (including Amazon SES) do not allow selection of custom | However, some mailers (including Amazon SES) do not allow selection of custom | ||||
"Message-ID" values and will ignore or replace the "Message-ID" in mail that | "Message-ID" values and will ignore or replace the "Message-ID" in mail that | ||||
is submitted through them. | is submitted through them. | ||||
When Phabricator adds other mail headers which affect threading, like | When Phorge adds other mail headers which affect threading, like | ||||
"In-Reply-To", it needs to know if its "Message-ID" headers will be respected | "In-Reply-To", it needs to know if its "Message-ID" headers will be respected | ||||
or not to select header values which will produce good threading behavior. If | or not to select header values which will produce good threading behavior. If | ||||
we guess wrong and think we can set a "Message-ID" header when we can't, you | we guess wrong and think we can set a "Message-ID" header when we can't, you | ||||
may get poor threading behavior in mail clients. | may get poor threading behavior in mail clients. | ||||
For most mailers (like Postmark, Mailgun, and Amazon SES), the correct setting | For most mailers (like Postmark, Mailgun, and Amazon SES), the correct setting | ||||
will be selected for you automatically, because the behavior of the mailer | will be selected for you automatically, because the behavior of the mailer | ||||
is knowable ahead of time. For example, we know Amazon SES will never respect | is knowable ahead of time. For example, we know Amazon SES will never respect | ||||
Show All 12 Lines | |||||
By default, we check if the mailer has a hostname we recognize as belonging | By default, we check if the mailer has a hostname we recognize as belonging | ||||
to a service which does not allow us to set a "Message-ID" header. If we don't | to a service which does not allow us to set a "Message-ID" header. If we don't | ||||
recognize the hostname (which is very common, since these services are most | recognize the hostname (which is very common, since these services are most | ||||
often configured against the localhost or some other local machine), we assume | often configured against the localhost or some other local machine), we assume | ||||
we can set a "Message-ID" header. | we can set a "Message-ID" header. | ||||
If the outbound pathway does not actually allow selection of a "Message-ID" | If the outbound pathway does not actually allow selection of a "Message-ID" | ||||
header, you can set the `message-id` option on the mailer to `false` to tell | header, you can set the `message-id` option on the mailer to `false` to tell | ||||
Phabricator that it should not assume it can select a value for this header. | Phorge that it should not assume it can select a value for this header. | ||||
For example, if you are sending mail via a local Postfix server which then | For example, if you are sending mail via a local Postfix server which then | ||||
forwards the mail to Amazon SES (a service which does not allow selection of | forwards the mail to Amazon SES (a service which does not allow selection of | ||||
a "Message-ID" header), your `smtp` configuration in Phabricator should | a "Message-ID" header), your `smtp` configuration in Phorge should | ||||
specify `"message-id": false`. | specify `"message-id": false`. | ||||
Next Steps | Next Steps | ||||
========== | ========== | ||||
Continue by: | Continue by: | ||||
- @{article:Configuring Inbound Email} so users can reply to email they | - @{article:Configuring Inbound Email} so users can reply to email they | ||||
receive about revisions and tasks to interact with them; or | receive about revisions and tasks to interact with them; or | ||||
- learning about daemons with @{article:Managing Daemons with phd}; or | - learning about daemons with @{article:Managing Daemons with phd}; or | ||||
- returning to the @{article:Configuration Guide}. | - returning to the @{article:Configuration Guide}. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0