configuring_outbound_email.diviner

@title Configuring Outbound Email
@group config

Instructions for configuring Phabricator to send mail.

= Overview =

Phabricator can send outbound email via several different adapters:

  - by running ##sendmail## on the local host with SMTP; or
  - by running postfix on the local host with SMTP; or
  - by using Amazon SES (Simple Email Service); or
  - by using SendGrid's REST API; or
  - via a custom adapter you write; or
  - by dropping email into a hole and not delivering it.

Of these, ##sendmail## is the default but requires some configuration. SES and
SendGrid are easier, but cost money and have some limitations. Writing a custom
solution requires digging into the code. See below for details on how to set up
each method.

Phabricator can also send outbound email in two ways:

  - immediately, when messages are generated (default); or
  - in the background, via a daemon.

Sending mail in the background requires that you be running the Phabricator
daemons, but can greatly improve the performance of the application if your mail
handler is slow. For more information on using daemons, see
@{article:Managing Daemons with phd}.

= Basics =

Regardless of how outbound email is delivered, you should configure these keys
in your configuration file:

  - **metamta.default-address** determines where mail is sent "From" by
    default. If your domain is ##example.org##, set this to something like
    "##noreply@example.org##".
  - **metamta.domain** should be set to your domain, e.g. "##example.org##".
  - **metamta.can-send-as-user** should be left as ##false## in most cases,
    but see the documentation in ##default.conf.php## for details.

= Configuring Mail Adapters =

To choose how mail will be sent, change the **metamta.mail-adapter** key in
your configuration. Possible values are:

  - ##PhabricatorMailImplementationPHPMailerLiteAdapter##: default, uses
    "sendmail", see "Adapter: Sendmail".
  - ##PhabricatorMailImplementationPHPMailerAdapter##: uses SMTP, see
    "Adapter: SMTP".
  - ##PhabricatorMailImplementationAmazonSESAdapter##: use Amazon SES, see
    "Adapter: Amazon SES".
  - ##PhabricatorMailImplementationSendGridAdapter##: use SendGrid, see
    "Adapter: SendGrid".
  - ##Some Custom Class You Write##: use a custom adapter you write, see
    "Adapter: Custom".
  - ##PhabricatorMailImplementationTestAdapter##: this will
    **completely disable** outbound mail. You can use this if you don't want to
    send outbound mail, or want to skip this step for now and configure it
    later.

= Adapter: Sendmail =

This is the default, and selected by choosing
##PhabricatorMailImplementationPHPMailerLiteAdapter## as the value for
**metamta.mail-adapter**. 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.

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
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
do any of this, consider using Amazon SES.

= Adapter: SMTP =

For most situations of using SMTP to send email, you could actually use
'sendmail' or 'postfix' to do it. But some SMTP server requires authentication 
and the 'sendmail' mailer doesn't work. If you want to try with postfix, for install
instructions, consult the documentation for postfix as MTA and you could configure 
to use SMTP then.

To configure Phabricator to use SMTP, set these configuration keys:

  - **metamta.mail-adapter**: set to
    "PhabricatorMailImplementationPHPMailerAdapter".
  - **phpmailer.mailer**: set to "smtp".
  - **phpmailer.smtp-host**: set to hostname of your smtp server.
  - **phpmailer.smtp-port**: set to port of your smtp server.
  - **phpmailer.smtp-user**: set to your username used for authentication.
  - **phpmailer.smtp-password**: set to your password used for authentication.

= Adapter: Amazon SES =

Amazon SES is Amazon's cloud email service. It is not free, but is easier to
configure than sendmail and can simplify outbound email configuration. To use
Amazon SES, you need to sign up for an account with Amazon at
<http://aws.amazon.com/ses/>.

To configure Phabricator to use Amazon SES, set these configuration keys:

  - **metamta.mail-adapter**: set to
    "PhabricatorMailImplementationAmazonSESAdapter".
  - **amazon-ses.access-key**: set to your Amazon SES access key.
  - **amazon-ses.secret-key**: set to your Amazon SES secret key.

NOTE: Amazon SES **requires you to verify your "From" address**. Configure 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!

NOTE: Amazon SES is slow to accept mail (often 1-2 seconds) and application
performance will improve greatly if you configure outbound email to send in
the background.

= Adapter: SendGrid =

SendGrid is an email delivery service like Amazon SES. You can learn more at
<http://sendgrid.com/>. It is easy to configure, but not free.

You can configure SendGrid in two ways: you can send via SMTP or via the REST
API. To use SMTP, just configure ##sendmail## and leave Phabricator's setup
with defaults. To use the REST API, follow the instructions in this section.

To configure Phabricator to use SendGrid, set these configuration keys:

  - **metamta.mail-adapter**: set to
    "PhabricatorMailImplementationSendGridAdapter".
  - **sendgrid.api-user**: set to your SendGrid login name.
  - **sendgrid.api-key**: set to your SendGrid password.

If you're logged into your SendGrid account, you may be able to find this
information easily by visiting <http://sendgrid.com/developer>.

= Adapter: Custom =

You can provide a custom adapter by writing a concrete subclass of
@{class:PhabricatorMailImplementationAdapter} and setting it as the
**metamta.mail-adapter**.

TODO: This needs to be better documented once extending Phabricator is better
documented.

= Adapter: Disable Outbound Mail =

You can use the @{class:PhabricatorMailImplementationTestAdapter} to completely
disable outbound mail, if you don't want to send mail or don't want to configure
it yet. Just set **metamta.mail-adapter** to
"PhabricatorMailImplementationTestAdapter".

= Configuring MetaMTA to Send Mail Using a Daemon =

Regardless of how you are sending outbound email, you can move the handoff to
the MTA out of the main process and into a daemon. This will greatly improve
application performance if your mailer is slow, like Amazon SES. In particular,
commenting on Differential Revisions and Maniphest Tasks sends outbound email.

If you set **metamta.send-immediately** to ##false## in your configuration,
MetaMTA will queue mail to be send by a PhabricatorTaskmasterDaemon.
For more information on using daemons, see @{article:Managing Daemons with phd}.

= Testing and Debugging Outbound Email =

Phabricator has a mail log and test console at ##/mail/##, or click the
**MetaMTA** link from the homepage. This console shows all the mail Phabricator
has attempted to deliver, plus debugging and error information.

You can use the "Send New Message" button to send mail using the current
configuration. This can help test that your setup is correct.

NOTE: when you send mail, "to" and "cc" must be valid users of the system, not
arbitrary email addresses.

You can monitor daemons using the Daemon Console (##/daemon/##, or click
**Daemon Console** from the homepage).

= Next Steps =

Continue by:

  - @{article:Configuring Inbound Email} so users can reply to email they
  receive about revisions and tasks to interact with them; or
  - learning about daemons with @{article:Managing Daemons with phd}; or
  - returning to the @{article:Configuration Guide}.