[Summary view] [Print] [Text view]

   1  @title Configuring Outbound Email
   2  @group config
   3  
   4  Instructions for configuring Phabricator to send mail.
   5  
   6  = Overview =
   7  
   8  Phabricator can send outbound email via several different providers, called
   9  "Adapters".
  10  
  11  | Send Mail With | Setup | Cost | Inbound | Notes |
  12  |---------|-------|------|---------|-------|
  13  | Mailgun | Easy | Cheap | Yes | Recommended |
  14  | Amazon SES | Easy | Cheap | No | Recommended |
  15  | SendGrid | Medium | Cheap | Yes | Discouraged (See Note) |
  16  | External SMTP | Medium | Varies | No | Gmail, etc. |
  17  | Local SMTP | Hard | Free | No | (Default) sendmail, postfix, etc |
  18  | Custom | Hard | Free | No | Write an adapter for some other service. |
  19  | Drop in a Hole | Easy | Free | No | Drops mail in a deep, dark hole. |
  20  
  21  Of these options, sending mail via local SMTP is the default, but usually
  22  requires some configuration to get working. See below for details on how to
  23  select and configure a delivery method.
  24  
  25  Overall, Mailgun and SES are much easier to set up, and using one of them is
  26  recommended. In particular, Mailgun will also let you set up inbound email
  27  easily.
  28  
  29  If you have some internal mail service you'd like to use you can also
  30  write a custom adapter, but this requires digging into the code.
  31  
  32  Phabricator sends mail in the background, so the daemons need to be running for
  33  it to be able to deliver mail. You should receive setup warnings if they are
  34  not. For more information on using daemons, see
  35  @{article:Managing Daemons with phd}.
  36  
  37  **Note on SendGrid**: Users have experienced a number of odd issues with
  38  SendGrid, compared to fewer issues with other mailers. We discourage SendGrid
  39  unless you're already using it. If you send to SendGrid via SMTP, you may need
  40  to adjust `phpmailer.smtp-encoding`.
  41  
  42  = Basics =
  43  
  44  Regardless of how outbound email is delivered, you should configure these keys
  45  in your configuration:
  46  
  47    - **metamta.default-address** determines where mail is sent "From" by
  48      default. If your domain is `example.org`, set this to something like
  49      `[email protected]`.
  50    - **metamta.domain** should be set to your domain, e.g. `example.org`.
  51    - **metamta.can-send-as-user** should be left as ##false## in most cases,
  52      but see the documentation for details.
  53  
  54  = Configuring Mail Adapters =
  55  
  56  To choose how mail will be sent, change the `metamta.mail-adapter` key in
  57  your configuration. Possible values are listed in the UI:
  58  
  59    - ##PhabricatorMailImplementationAmazonMailgunAdapter##: use Mailgun, see
  60      "Adapter: Mailgun".
  61    - ##PhabricatorMailImplementationAmazonSESAdapter##: use Amazon SES, see
  62      "Adapter: Amazon SES".
  63    - ##PhabricatorMailImplementationPHPMailerLiteAdapter##: default, uses
  64      "sendmail", see "Adapter: Sendmail".
  65    - ##PhabricatorMailImplementationPHPMailerAdapter##: uses SMTP, see
  66      "Adapter: SMTP".
  67    - ##PhabricatorMailImplementationSendGridAdapter##: use SendGrid, see
  68      "Adapter: SendGrid".
  69    - ##Some Custom Class You Write##: use a custom adapter you write, see
  70      "Adapter: Custom".
  71    - ##PhabricatorMailImplementationTestAdapter##: this will
  72      **completely disable** outbound mail. You can use this if you don't want to
  73      send outbound mail, or want to skip this step for now and configure it
  74      later.
  75  
  76  = Adapter: Sendmail =
  77  
  78  This is the default, and selected by choosing
  79  `PhabricatorMailImplementationPHPMailerLiteAdapter` as the value for
  80  **metamta.mail-adapter**. This requires a `sendmail` binary to be installed on
  81  the system. Most MTAs (e.g., sendmail, qmail, postfix) should do this, but your
  82  machine may not have one installed by default. For install instructions, consult
  83  the documentation for your favorite MTA.
  84  
  85  Since you'll be sending the mail yourself, you are subject to things like SPF
  86  rules, blackholes, and MTA configuration which are beyond the scope of this
  87  document. If you can already send outbound email from the command line or know
  88  how to configure it, this option is straightforward. If you have no idea how to
  89  do any of this, strongly consider using Mailgun or Amazon SES instead.
  90  
  91  If you experience issues with mail getting mangled (for example, arriving with
  92  too many or too few newlines) you may try adjusting `phpmailer.smtp-encoding`.
  93  
  94  = Adapter: SMTP =
  95  
  96  You can use this adapter to send mail via an external SMTP server, like Gmail.
  97  To do this, set these configuration keys:
  98  
  99    - **metamta.mail-adapter**: set to
 100      `PhabricatorMailImplementationPHPMailerAdapter`.
 101    - **phpmailer.mailer**: set to `smtp`.
 102    - **phpmailer.smtp-host**: set to hostname of your SMTP server.
 103    - **phpmailer.smtp-port**: set to port of your SMTP server.
 104    - **phpmailer.smtp-user**: set to your username used for authentication.
 105    - **phpmailer.smtp-password**: set to your password used for authentication.
 106    - **phpmailer.smtp-protocol**: set to `tls` or `ssl` if necessary. Use
 107      `ssl` for Gmail.
 108    - **phpmailer.smtp-encoding**: Normally safe to leave as the default, but
 109      adjusting it may help resolve mail mangling issues (for example, mail
 110      arriving with too many or too few newlines).
 111  
 112  = Adapter: Mailgun =
 113  
 114  Mailgun is an email delivery service. You can learn more at
 115  <http://www.mailgun.com>. Mailgun isn't free, but is very easy to configure
 116  and works well.
 117  
 118  To use Mailgun, sign up for an account, then set these configuration keys:
 119  
 120    - **metamta.mail-adapter**: set to
 121      `PhabricatorMailImplementationMailgunAdapter`.
 122    - **mailgun.api-key**: set to your Mailgun API key.
 123    - **mailgun.domain**: set to your Mailgun domain.
 124  
 125  = Adapter: Amazon SES =
 126  
 127  Amazon SES is Amazon's cloud email service. It is not free, but is easier to
 128  configure than sendmail and can simplify outbound email configuration. To use
 129  Amazon SES, you need to sign up for an account with Amazon at
 130  <http://aws.amazon.com/ses/>.
 131  
 132  To configure Phabricator to use Amazon SES, set these configuration keys:
 133  
 134    - **metamta.mail-adapter**: set to
 135      "PhabricatorMailImplementationAmazonSESAdapter".
 136    - **amazon-ses.access-key**: set to your Amazon SES access key.
 137    - **amazon-ses.secret-key**: set to your Amazon SES secret key.
 138  
 139  NOTE: Amazon SES **requires you to verify your "From" address**. Configure which
 140  "From" address to use by setting "##metamta.default-address##" in your config,
 141  then follow the Amazon SES verification process to verify it. You won't be able
 142  to send email until you do this!
 143  
 144  = Adapter: SendGrid =
 145  
 146  SendGrid is an email delivery service like Amazon SES. You can learn more at
 147  <http://sendgrid.com/>. It is easy to configure, but not free.
 148  
 149  You can configure SendGrid in two ways: you can send via SMTP or via the REST
 150  API. To use SMTP, just configure ##sendmail## and leave Phabricator's setup
 151  with defaults. To use the REST API, follow the instructions in this section.
 152  
 153  To configure Phabricator to use SendGrid, set these configuration keys:
 154  
 155    - **metamta.mail-adapter**: set to
 156      "PhabricatorMailImplementationSendGridAdapter".
 157    - **sendgrid.api-user**: set to your SendGrid login name.
 158    - **sendgrid.api-key**: set to your SendGrid password.
 159  
 160  If you're logged into your SendGrid account, you may be able to find this
 161  information easily by visiting <http://sendgrid.com/developer>.
 162  
 163  = Adapter: Custom =
 164  
 165  You can provide a custom adapter by writing a concrete subclass of
 166  @{class:PhabricatorMailImplementationAdapter} and setting it as the
 167  `metamta.mail-adapter`.
 168  
 169  TODO: This should be better documented once extending Phabricator is better
 170  documented.
 171  
 172  = Adapter: Disable Outbound Mail =
 173  
 174  You can use the @{class:PhabricatorMailImplementationTestAdapter} to completely
 175  disable outbound mail, if you don't want to send mail or don't want to configure
 176  it yet. Just set **metamta.mail-adapter** to
 177  `PhabricatorMailImplementationTestAdapter`.
 178  
 179  = Testing and Debugging Outbound Email =
 180  
 181  You can use the `bin/mail` utility to test, debug, and examine outbound mail. In
 182  particular:
 183  
 184    phabricator/ $ ./bin/mail list-outbound   # List outbound mail.
 185    phabricator/ $ ./bin/mail show-outbound   # Show details about messages.
 186    phabricator/ $ ./bin/mail send-test       # Send test messages.
 187  
 188  Run `bin/mail help <command>` for more help on using these commands.
 189  
 190  You can monitor daemons using the Daemon Console (##/daemon/##, or click
 191  **Daemon Console** from the homepage).
 192  
 193  = Next Steps =
 194  
 195  Continue by:
 196  
 197    - @{article:Configuring Inbound Email} so users can reply to email they
 198    receive about revisions and tasks to interact with them; or
 199    - learning about daemons with @{article:Managing Daemons with phd}; or
 200    - returning to the @{article:Configuration Guide}.