[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  final class PhabricatorMetaMTAConfigOptions
   4    extends PhabricatorApplicationConfigOptions {
   5  
   6    public function getName() {
   7      return pht('Mail');
   8    }
   9  
  10    public function getDescription() {
  11      return pht('Configure Mail.');
  12    }
  13  
  14    public function getOptions() {
  15      $send_as_user_desc = $this->deformat(pht(<<<EODOC
  16  When a user takes an action which generates an email notification (like
  17  commenting on a Differential revision), Phabricator can either send that mail
  18  "From" the user's email address (like "[email protected]") or "From" the
  19  'metamta.default-address' address.
  20  
  21  The user experience is generally better if Phabricator uses the user's real
  22  address as the "From" since the messages are easier to organize when they appear
  23  in mail clients, but this will only work if the server is authorized to send
  24  email on behalf of the "From" domain. Practically, this means:
  25  
  26    - If you are doing an install for Example Corp and all the users will have
  27      corporate @corp.example.com addresses and any hosts Phabricator is running
  28      on are authorized to send email from corp.example.com, you can enable this
  29      to make the user experience a little better.
  30    - If you are doing an install for an open source project and your users will
  31      be registering via Facebook and using personal email addresses, you probably
  32      should not enable this or all of your outgoing email might vanish into SFP
  33      blackholes.
  34    - If your install is anything else, you're safer leaving this off, at least
  35      initially, since the risk in turning it on is that your outgoing mail will
  36      never arrive.
  37  EODOC
  38  ));
  39  
  40      $one_mail_per_recipient_desc = $this->deformat(pht(<<<EODOC
  41  When a message is sent to multiple recipients (for example, several reviewers on
  42  a code review), Phabricator can either deliver one email to everyone (e.g., "To:
  43  alincoln, usgrant, htaft") or separate emails to each user (e.g., "To:
  44  alincoln", "To: usgrant", "To: htaft"). The major advantages and disadvantages
  45  of each approach are:
  46  
  47    - One mail to everyone:
  48      - Recipients can see To/Cc at a glance.
  49      - If you use mailing lists, you won't get duplicate mail if you're
  50        a normal recipient and also Cc'd on a mailing list.
  51      - Getting threading to work properly is harder, and probably requires
  52        making mail less useful by turning off options.
  53      - Sometimes people will "Reply All" and everyone will get two mails,
  54        one from the user and one from Phabricator turning their mail into
  55        a comment.
  56      - Not supported with a private reply-to address.
  57      - Mails are sent in the server default translation.
  58    - One mail to each user:
  59      - Recipients need to look in the mail body to see To/Cc.
  60      - If you use mailing lists, recipients may sometimes get duplicate
  61        mail.
  62      - Getting threading to work properly is easier, and threading settings
  63        can be customzied by each user.
  64      - "Reply All" no longer spams all other users.
  65      - Required if private reply-to addresses are configured.
  66      - Mails are sent in the language of user preference.
  67  
  68  In the code, splitting one outbound email into one-per-recipient is sometimes
  69  referred to as "multiplexing".
  70  EODOC
  71  ));
  72  
  73      $herald_hints_description = $this->deformat(pht(<<<EODOC
  74  You can disable the Herald hints in email if users prefer smaller messages.
  75  These are the links under the header "WHY DID I GET THIS EMAIL?". If you set
  76  this to true, they will not appear in any mail. Users can still navigate to
  77  the links via the web interface.
  78  EODOC
  79  ));
  80  
  81      $reply_hints_description = $this->deformat(pht(<<<EODOC
  82  You can disable the hints under "REPLY HANDLER ACTIONS" if users prefer
  83  smaller messages. The actions themselves will still work properly.
  84  EODOC
  85  ));
  86  
  87      $recipient_hints_description = $this->deformat(pht(<<<EODOC
  88  You can disable the "To:" and "Cc:" footers in mail if users prefer smaller
  89  messages.
  90  EODOC
  91  ));
  92  
  93      $bulk_description = $this->deformat(pht(<<<EODOC
  94  If this option is enabled, Phabricator will add a "Precedence: bulk" header to
  95  transactional mail (e.g., Differential, Maniphest and Herald notifications).
  96  This may improve the behavior of some auto-responder software and prevent it
  97  from replying. However, it may also cause deliverability issues -- notably, you
  98  currently can not send this header via Amazon SES, and enabling this option with
  99  SES will prevent delivery of any affected mail.
 100  EODOC
 101  ));
 102  
 103      $email_preferences_description = $this->deformat(pht(<<<EODOC
 104  You can disable the email preference link in emails if users prefer smaller
 105  emails.
 106  EODOC
 107  ));
 108  
 109      $re_prefix_description = $this->deformat(pht(<<<EODOC
 110  Mail.app on OS X Lion won't respect threading headers unless the subject is
 111  prefixed with "Re:". If you enable this option, Phabricator will add "Re:" to
 112  the subject line of all mail which is expected to thread. If you've set
 113  'metamta.one-mail-per-recipient', users can override this setting in their
 114  preferences.
 115  EODOC
 116  ));
 117  
 118      $vary_subjects_description = $this->deformat(pht(<<<EODOC
 119  If true, allow MetaMTA to change mail subjects to put text like '[Accepted]' and
 120  '[Commented]' in them. This makes subjects more useful, but might break
 121  threading on some clients. If you've set 'metamta.one-mail-per-recipient', users
 122  can override this setting in their preferences.
 123  EODOC
 124  ));
 125  
 126      $reply_to_description = $this->deformat(pht(<<<EODOC
 127  If you enable {{metamta.public-replies}}, Phabricator uses "From" to
 128  authenticate users. You can additionally enable this setting to try to
 129  authenticate with 'Reply-To'. Note that this is completely spoofable and
 130  insecure (any user can set any 'Reply-To' address) but depending on the nature
 131  of your install or other deliverability conditions this might be okay.
 132  Generally, you can't do much more by spoofing Reply-To than be annoying (you can
 133  write but not read content). But this is still **COMPLETELY INSECURE**.
 134  EODOC
 135  ));
 136  
 137      $adapter_description = $this->deformat(pht(<<<EODOC
 138  Adapter class to use to transmit mail to the MTA. The default uses
 139  PHPMailerLite, which will invoke "sendmail". This is appropriate if sendmail
 140  actually works on your host, but if you haven't configured mail it may not be so
 141  great. A number of other mailers are available (e.g., SES, SendGrid, SMTP,
 142  custom mailers), consult "Configuring Outbound Email" in the documentation for
 143  details.
 144  EODOC
 145  ));
 146  
 147      $placeholder_description = $this->deformat(pht(<<<EODOC
 148  When sending a message that has no To recipient (i.e. all recipients are CC'd,
 149  for example when multiplexing mail), set the To field to the following value. If
 150  no value is set, messages with no To will have their CCs upgraded to To.
 151  EODOC
 152  ));
 153  
 154      $public_replies_description = $this->deformat(pht(<<<EODOC
 155  By default, Phabricator generates unique reply-to addresses and sends a separate
 156  email to each recipient when you enable reply handling. This is more secure than
 157  using "From" to establish user identity, but can mean users may receive multiple
 158  emails when they are on mailing lists. Instead, you can use a single, non-unique
 159  reply to address and authenticate users based on the "From" address by setting
 160  this to 'true'. This trades away a little bit of security for convenience, but
 161  it's reasonable in many installs. Object interactions are still protected using
 162  hashes in the single public email address, so objects can not be replied to
 163  blindly.
 164  EODOC
 165  ));
 166  
 167      $single_description = $this->deformat(pht(<<<EODOC
 168  If you want to use a single mailbox for Phabricator reply mail, you can use this
 169  and set a common prefix for reply addresses generated by Phabricator. It will
 170  make use of the fact that a mail-address such as
 171  `[email protected]` will be delivered to the `phabricator`
 172  user's mailbox. Set this to the left part of the email address and it will be
 173  prepended to all generated reply addresses.
 174  
 175  For example, if you want to use `[email protected]`, this should be set
 176  to `phabricator`.
 177  EODOC
 178  ));
 179  
 180      $address_description = $this->deformat(pht(<<<EODOC
 181  When email is sent, what format should Phabricator use for user's email
 182  addresses? Valid values are:
 183  
 184   - `short`: 'gwashington <[email protected]>'
 185   - `real`:  'George Washington <[email protected]>'
 186   - `full`: 'gwashington (George Washington) <[email protected]>'
 187  
 188  The default is `full`.
 189  EODOC
 190  ));
 191  
 192      return array(
 193        $this->newOption(
 194          'metamta.default-address',
 195          'string',
 196          '[email protected]')
 197          ->setDescription(pht('Default "From" address.')),
 198        $this->newOption(
 199          'metamta.domain',
 200          'string',
 201          'phabricator.example.com')
 202          ->setDescription(pht('Domain used to generate Message-IDs.')),
 203        $this->newOption(
 204          'metamta.mail-adapter',
 205          'class',
 206          'PhabricatorMailImplementationPHPMailerLiteAdapter')
 207          ->setBaseClass('PhabricatorMailImplementationAdapter')
 208          ->setSummary(pht('Control how mail is sent.'))
 209          ->setDescription($adapter_description),
 210        $this->newOption(
 211          'metamta.one-mail-per-recipient',
 212          'bool',
 213          true)
 214          ->setBoolOptions(
 215            array(
 216              pht('Send Mail To Each Recipient'),
 217              pht('Send Mail To All Recipients'),
 218            ))
 219          ->setSummary(
 220            pht(
 221              'Controls whether Phabricator sends one email with multiple '.
 222              'recipients in the "To:" line, or multiple emails, each with a '.
 223              'single recipient in the "To:" line.'))
 224          ->setDescription($one_mail_per_recipient_desc),
 225        $this->newOption('metamta.can-send-as-user', 'bool', false)
 226          ->setBoolOptions(
 227            array(
 228              pht('Send as User Taking Action'),
 229              pht('Send as Phabricator'),
 230            ))
 231          ->setSummary(
 232            pht(
 233              'Controls whether Phabricator sends email "From" users.'))
 234          ->setDescription($send_as_user_desc),
 235        $this->newOption(
 236          'metamta.reply-handler-domain',
 237          'string',
 238          'phabricator.example.com')
 239          ->setDescription(pht(
 240            'Domain used for reply email addresses. Some applications can '.
 241            'configure this domain.')),
 242        $this->newOption('metamta.reply.show-hints', 'bool', true)
 243          ->setBoolOptions(
 244            array(
 245              pht('Show Reply Handler Hints'),
 246              pht('No Reply Handler Hints'),
 247            ))
 248          ->setSummary(pht('Show hints about reply handler actions in email.'))
 249          ->setDescription($reply_hints_description),
 250        $this->newOption('metamta.herald.show-hints', 'bool', true)
 251          ->setBoolOptions(
 252            array(
 253              pht('Show Herald Hints'),
 254              pht('No Herald Hints'),
 255            ))
 256          ->setSummary(pht('Show hints about Herald rules in email.'))
 257          ->setDescription($herald_hints_description),
 258        $this->newOption('metamta.recipients.show-hints', 'bool', true)
 259          ->setBoolOptions(
 260            array(
 261              pht('Show Recipient Hints'),
 262              pht('No Recipient Hints'),
 263            ))
 264          ->setSummary(pht('Show "To:" and "Cc:" footer hints in email.'))
 265          ->setDescription($recipient_hints_description),
 266        $this->newOption('metamta.email-preferences', 'bool', true)
 267          ->setBoolOptions(
 268            array(
 269              pht('Show Email Preferences Link'),
 270              pht('No Email Preferences Link'),
 271            ))
 272          ->setSummary(pht('Show email preferences link in email.'))
 273          ->setDescription($email_preferences_description),
 274        $this->newOption('metamta.precedence-bulk', 'bool', false)
 275          ->setBoolOptions(
 276            array(
 277              pht('Add "Precedence: bulk" Header'),
 278              pht('No "Precedence: bulk" Header'),
 279            ))
 280          ->setSummary(pht('Control the "Precedence: bulk" header.'))
 281          ->setDescription($bulk_description),
 282        $this->newOption('metamta.re-prefix', 'bool', false)
 283          ->setBoolOptions(
 284            array(
 285              pht('Force "Re:" Subject Prefix'),
 286              pht('No "Re:" Subject Prefix'),
 287            ))
 288          ->setSummary(pht('Control "Re:" subject prefix, for Mail.app.'))
 289          ->setDescription($re_prefix_description),
 290        $this->newOption('metamta.vary-subjects', 'bool', true)
 291          ->setBoolOptions(
 292            array(
 293              pht('Allow Varied Subjects'),
 294              pht('Always Use the Same Thread Subject'),
 295            ))
 296          ->setSummary(pht('Control subject variance, for some mail clients.'))
 297          ->setDescription($vary_subjects_description),
 298        $this->newOption('metamta.insecure-auth-with-reply-to', 'bool', false)
 299          ->setBoolOptions(
 300            array(
 301              pht('Allow Insecure Reply-To Auth'),
 302              pht('Disallow Reply-To Auth'),
 303            ))
 304          ->setSummary(pht('Trust "Reply-To" headers for authentication.'))
 305          ->setDescription($reply_to_description),
 306        $this->newOption('metamta.placeholder-to-recipient', 'string', null)
 307          ->setSummary(pht('Placeholder for mail with only CCs.'))
 308          ->setDescription($placeholder_description),
 309        $this->newOption('metamta.public-replies', 'bool', false)
 310          ->setBoolOptions(
 311            array(
 312              pht('Use Public Replies (Less Secure)'),
 313              pht('Use Private Replies (More Secure)'),
 314            ))
 315          ->setSummary(
 316            pht(
 317              'Phabricator can use less-secure but mailing list friendly public '.
 318              'reply addresses.'))
 319          ->setDescription($public_replies_description),
 320        $this->newOption('metamta.single-reply-handler-prefix', 'string', null)
 321          ->setSummary(
 322            pht('Allow Phabricator to use a single mailbox for all replies.'))
 323          ->setDescription($single_description),
 324        $this->newOption('metamta.user-address-format', 'enum', 'full')
 325          ->setEnumOptions(
 326            array(
 327              'short' => 'short',
 328              'real' => 'real',
 329              'full' => 'full',
 330            ))
 331          ->setSummary(pht('Control how Phabricator renders user names in mail.'))
 332          ->setDescription($address_description)
 333          ->addExample('gwashington <[email protected]>', 'short')
 334          ->addExample('George Washington <[email protected]>', 'real')
 335          ->addExample(
 336            'gwashington (George Washington) <[email protected]>',
 337            'full'),
 338        $this->newOption('metamta.email-body-limit', 'int', 524288)
 339          ->setDescription(
 340            pht(
 341              'You can set a limit for the maximum byte size of outbound mail. '.
 342              'Mail which is larger than this limit will be truncated before '.
 343              'being sent. This can be useful if your MTA rejects mail which '.
 344              'exceeds some limit (this is reasonably common). Specify a value '.
 345              'in bytes.'))
 346          ->setSummary(pht('Global cap for size of generated emails (bytes).'))
 347          ->addExample(524288, pht('Truncate at 512KB'))
 348          ->addExample(1048576, pht('Truncate at 1MB')),
 349      );
 350    }
 351  
 352  }