Differential D19973 Diff 47712 src/docs/user/configuration/configuring_outbound_email.diviner

Changeset 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 mail.		Instructions for configuring Phabricator to send mail.

Overview		Overview
========		========

Phabricator can send outbound email through several different mail services,		Phabricator can send outbound email through several different mail services,
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 \| Notes \|		\| Send Mail With \| Setup \| Cost \| Inbound \| Notes \|
\|---------\|-------\|------\|---------\|-------\|		\|---------\|-------\|------\|---------\|-------\|
\| Mailgun \| Easy \| Cheap \| Yes \| Recommended \|
\| Postmark \| Easy \| Cheap \| Yes \| Recommended \|		\| Postmark \| Easy \| Cheap \| Yes \| Recommended \|
		\| Mailgun \| Easy \| Cheap \| Yes \| Recommended \|
\| Amazon SES \| Easy \| Cheap \| No \| Recommended \|		\| Amazon SES \| Easy \| Cheap \| No \| Recommended \|
\| SendGrid \| Medium \| Cheap \| Yes \| Discouraged \|		\| SendGrid \| Medium \| Cheap \| Yes \| Discouraged \|
\| External SMTP \| Medium \| Varies \| No \| Gmail, etc. \|		\| External SMTP \| Medium \| Varies \| No \| Gmail, etc. \|
\| Local SMTP \| Hard \| Free \| No \| sendmail, postfix, etc \|		\| Local SMTP \| Hard \| Free \| No \| sendmail, postfix, etc \|
\| Custom \| Hard \| Free \| No \| Write a custom mailer for some other service. \|		\| 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. \|		\| Drop in a Hole \| Easy \| Free \| No \| Drops mail in a deep, dark hole. \|

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.

Overall, Mailgun and SES are much easier to set up, and using one of them is		Overall, Postmark and Mailgun are much easier to set up, and using one of them
recommended. In particular, Mailgun will also let you set up inbound email		is recommended. Both will also let you set up inbound email easily.
easily.

If you have some internal mail service you'd like to use you can also		If you have some internal mail service you'd like to use you can also write a
write a custom mailer, but this requires digging into the code.		custom mailer, but this requires digging into the code.

		amckinleyUnsubmitted Not Done Inline Actions "This workplace has not an API change in `1` days." amckinley: "This workplace has not an API change in {key 1} days."
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
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}.


Basics		Basics
======		======

Regardless of how outbound email is delivered, you should configure these keys		Before configuring outbound mail, you should first set up
in your configuration:		`metamta.default-address` in Configuration. This determines where mail is sent
		"From" by default.

- metamta.default-address determines where mail is sent "From" by		If your domain is `example.org`, set this to something
default. If your domain is `example.org`, set this to something like		like `noreply@example.org`.
`noreply@example.org`.
- metamta.can-send-as-user should be left as `false` in most cases,		Ideally, this should be a valid, deliverable address that doesn't bounce if
but see the documentation for details.		users accidentally send mail to it.


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
can configure multiple mailers to provide greater availability in the event of		can configure multiple mailers to provide greater availability in the event of
Show All 32 Lines	- `media`: Optional list<string>. Some mailers support delivering multiple
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 third-party mailers:		The `type` field can be used to select these third-party mailers:

- `mailgun`: Use Mailgun.		- `mailgun`: Use Mailgun.
- `ses`: Use Amazon SES.		- `ses`: Use Amazon SES.
- `sendgrid`: Use Sendgrid.		- `sendgrid`: Use SendGrid.
- `postmark`: Use Postmark.		- `postmark`: Use Postmark.

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		You can also write your own mailer by extending `PhabricatorMailAdapter`.
`PhabricatorMailAdapter`.

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.

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.


Setting Complex Configuration		Setting Complex Configuration
=============================		=============================

Show All 23 Lines
```		```
phabricator/ $ ./bin/config set --stdin cluster.mailers < mailers.json		phabricator/ $ ./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: Mailgun
===============

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.

To use this mailer, set `type` to `mailgun`, then configure these `options`:

- `api-key`: Required string. Your Mailgun API key.
- `domain`: Required string. Your Mailgun domain.


Mailer: Postmark		Mailer: Postmark
================		================

Postmark is a third-party email delivery serivice. You can learn more at		Postmark is a third-party email delivery service. You can learn more at
<https://www.postmarkapp.com/>.		<https://www.postmarkapp.com/>.

To use this mailer, set `type` to `postmark`, then configure these `options`:		To use this mailer, set `type` to `postmark`, then configure these `options`:

- `access-token`: Required string. Your Postmark access token.		- `access-token`: Required string. Your Postmark access token.
- `inbound-addresses`: Optional list<string>. Address ranges which you		- `inbound-addresses`: Optional list<string>. Address ranges which you
will accept inbound Postmark HTTP webook requests from.		will accept inbound Postmark HTTP webook requests from.

Show All 10 Lines	[
"18.217.206.57/32"		"18.217.206.57/32"
]		]
```		```

The default address ranges were last updated in January 2019, and were		The default address ranges were last updated in January 2019, 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
		===============

		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.

		To use this mailer, set `type` to `mailgun`, then configure these `options`:

		- `api-key`: Required string. Your Mailgun API key.
		- `domain`: Required string. Your Mailgun domain.


Mailer: Amazon SES		Mailer: Amazon SES
==================		==================

Amazon SES is Amazon's cloud email service. You can learn more at		Amazon SES is Amazon's cloud email service. You can learn more at
<http://aws.amazon.com/ses/>.		<http://aws.amazon.com/ses/>.

To use this mailer, set `type` to `ses`, then configure these `options`:		To use this mailer, set `type` to `ses`, then configure these `options`:

- `access-key`: Required string. Your Amazon SES access key.		- `access-key`: Required string. Your Amazon SES access key.
- `secret-key`: Required string. Your Amazon SES secret key.		- `secret-key`: Required string. Your Amazon SES secret key.
- `endpoint`: Required string. Your Amazon SES endpoint.		- `endpoint`: Required string. Your Amazon SES endpoint.

NOTE: Amazon SES requires you to verify your "From" address. Configure		NOTE: Amazon SES requires you to verify your "From" address. Configure
which "From" address to use by setting "`metamta.default-address`" in your		which "From" address to use by setting `metamta.default-address` in your
config, then follow the Amazon SES verification process to verify it. You		config, then follow the Amazon SES verification process to verify it. You
won't be able to send email until you do this!		won't be able to send email until you do this!


Mailer: SendGrid		Mailer: SendGrid
================		================

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
<http://sendgrid.com/>.		<http://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 Phabricator 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-user`: Required string. Your SendGrid login name.
- `api-key`: Required string. Your SendGrid API key.		- `api-key`: Required string. Your SendGrid API key.

NOTE: Users have experienced a number of odd issues with SendGrid, compared to		Older versions of the SendGrid API used different sets of credentials,
fewer issues with other mailers. We discourage SendGrid unless you're already		including an "API User". Make sure you're configuring your "API Key".
using it.


Mailer: Sendmail		Mailer: Sendmail
================		================

This requires a `sendmail` binary to be installed on		This requires a `sendmail` binary to be installed on the system. Most MTAs
the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your		(e.g., sendmail, qmail, postfix) should do this, but your machine may not have
machine may not have one installed by default. For install instructions, consult		one installed by default. For install instructions, consult the documentation
the documentation for your favorite MTA.		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 Mailgun or Amazon SES instead.		do any of this, strongly consider using Postmark or Mailgun instead.

To use this mailer, set `type` to `sendmail`. There are no `options` to		To use this mailer, set `type` to `sendmail`. There are no `options` to
configure.		configure.


Mailer: SMTP		Mailer: SMTP
============		============

▲ Show 20 Lines • Show All 93 Lines • Show Last 20 Lines