src/applications/config/option/PhabricatorMetaMTAConfigOptions.php

   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 getIcon() {
  15     return 'fa-send';
  16   }
  17
  18   public function getGroup() {
  19     return 'core';
  20   }
  21
  22   public function getOptions() {
  23     $send_as_user_desc = $this->deformat(pht(<<<EODOC
  24 When a user takes an action which generates an email notification (like
  25 commenting on a Differential revision), Phabricator can either send that mail
  26 "From" the user's email address (like "alincoln@logcabin.com") or "From" the
  27 '%s' address.
  28
  29 The user experience is generally better if Phabricator uses the user's real
  30 address as the "From" since the messages are easier to organize when they appear
  31 in mail clients, but this will only work if the server is authorized to send
  32 email on behalf of the "From" domain. Practically, this means:
  33
  34   - If you are doing an install for Example Corp and all the users will have
  35     corporate @corp.example.com addresses and any hosts Phabricator is running
  36     on are authorized to send email from corp.example.com, you can enable this
  37     to make the user experience a little better.
  38   - If you are doing an install for an open source project and your users will
  39     be registering via Facebook and using personal email addresses, you probably
  40     should not enable this or all of your outgoing email might vanish into SFP
  41     blackholes.
  42   - If your install is anything else, you're safer leaving this off, at least
  43     initially, since the risk in turning it on is that your outgoing mail will
  44     never arrive.
  45 EODOC
  46   ,
  47   'metamta.default-address'));
  48
  49     $one_mail_per_recipient_desc = $this->deformat(pht(<<<EODOC
  50 When a message is sent to multiple recipients (for example, several reviewers on
  51 a code review), Phabricator can either deliver one email to everyone (e.g., "To:
  52 alincoln, usgrant, htaft") or separate emails to each user (e.g., "To:
  53 alincoln", "To: usgrant", "To: htaft"). The major advantages and disadvantages
  54 of each approach are:
  55
  56   - One mail to everyone:
  57     - This violates policy controls. The body of the mail is generated without
  58       respect for object policies.
  59     - Recipients can see To/Cc at a glance.
  60     - If you use mailing lists, you won't get duplicate mail if you're
  61       a normal recipient and also Cc'd on a mailing list.
  62     - Getting threading to work properly is harder, and probably requires
  63       making mail less useful by turning off options.
  64     - Sometimes people will "Reply All", which can send mail to too many
  65       recipients. Phabricator will try not to send mail to users who already
  66       received a similar message, but can not prevent all stray email arising
  67       from "Reply All".
  68     - Not supported with a private reply-to address.
  69     - Mail messages are sent in the server default translation.
  70     - Mail that must be delivered over secure channels will leak the recipient
  71       list in the "To" and "Cc" headers.
  72   - One mail to each user:
  73     - Policy controls work correctly and are enforced per-user.
  74     - Recipients need to look in the mail body to see To/Cc.
  75     - If you use mailing lists, recipients may sometimes get duplicate
  76       mail.
  77     - Getting threading to work properly is easier, and threading settings
  78       can be customzied by each user.
  79     - "Reply All" will never send extra mail to other users involved in the
  80       thread.
  81     - Required if private reply-to addresses are configured.
  82     - Mail messages are sent in the language of user preference.
  83
  84 EODOC
  85 ));
  86
  87     $reply_hints_description = $this->deformat(pht(<<<EODOC
  88 You can disable the hints under "REPLY HANDLER ACTIONS" if users prefer
  89 smaller messages. The actions themselves will still work properly.
  90 EODOC
  91 ));
  92
  93     $recipient_hints_description = $this->deformat(pht(<<<EODOC
  94 You can disable the "To:" and "Cc:" footers in mail if users prefer smaller
  95 messages.
  96 EODOC
  97 ));
  98
  99     $email_preferences_description = $this->deformat(pht(<<<EODOC
 100 You can disable the email preference link in emails if users prefer smaller
 101 emails.
 102 EODOC
 103 ));
 104
 105     $re_prefix_description = $this->deformat(pht(<<<EODOC
 106 Mail.app on OS X Lion won't respect threading headers unless the subject is
 107 prefixed with "Re:". If you enable this option, Phabricator will add "Re:" to
 108 the subject line of all mail which is expected to thread. If you've set
 109 'metamta.one-mail-per-recipient', users can override this setting in their
 110 preferences.
 111 EODOC
 112 ));
 113
 114     $vary_subjects_description = $this->deformat(pht(<<<EODOC
 115 If true, allow MetaMTA to change mail subjects to put text like '[Accepted]' and
 116 '[Commented]' in them. This makes subjects more useful, but might break
 117 threading on some clients. If you've set '%s', users can override this setting
 118 in their preferences.
 119 EODOC
 120   ,
 121   'metamta.one-mail-per-recipient'));
 122
 123     $reply_to_description = $this->deformat(pht(<<<EODOC
 124 If you enable `%s`, Phabricator uses "From" to authenticate users. You can
 125 additionally enable this setting to try to authenticate with 'Reply-To'. Note
 126 that this is completely spoofable and insecure (any user can set any 'Reply-To'
 127 address) but depending on the nature of your install or other deliverability
 128 conditions this might be okay. Generally, you can't do much more by spoofing
 129 Reply-To than be annoying (you can write but not read content). But this is
 130 still **COMPLETELY INSECURE**.
 131 EODOC
 132   ,
 133   'metamta.public-replies'));
 134
 135     $adapter_description = $this->deformat(pht(<<<EODOC
 136 Adapter class to use to transmit mail to the MTA. The default uses
 137 PHPMailerLite, which will invoke "sendmail". This is appropriate if sendmail
 138 actually works on your host, but if you haven't configured mail it may not be so
 139 great. A number of other mailers are available (e.g., SES, SendGrid, SMTP,
 140 custom mailers). This option is deprecated in favor of 'cluster.mailers'.
 141 EODOC
 142 ));
 143
 144     $public_replies_description = $this->deformat(pht(<<<EODOC
 145 By default, Phabricator generates unique reply-to addresses and sends a separate
 146 email to each recipient when you enable reply handling. This is more secure than
 147 using "From" to establish user identity, but can mean users may receive multiple
 148 emails when they are on mailing lists. Instead, you can use a single, non-unique
 149 reply to address and authenticate users based on the "From" address by setting
 150 this to 'true'. This trades away a little bit of security for convenience, but
 151 it's reasonable in many installs. Object interactions are still protected using
 152 hashes in the single public email address, so objects can not be replied to
 153 blindly.
 154 EODOC
 155 ));
 156
 157     $single_description = $this->deformat(pht(<<<EODOC
 158 If you want to use a single mailbox for Phabricator reply mail, you can use this
 159 and set a common prefix for reply addresses generated by Phabricator. It will
 160 make use of the fact that a mail-address such as
 161 `phabricator+D123+1hjk213h@example.com` will be delivered to the `phabricator`
 162 user's mailbox. Set this to the left part of the email address and it will be
 163 prepended to all generated reply addresses.
 164
 165 For example, if you want to use `phabricator@example.com`, this should be set
 166 to `phabricator`.
 167 EODOC
 168 ));
 169
 170     $address_description = $this->deformat(pht(<<<EODOC
 171 When email is sent, what format should Phabricator use for user's email
 172 addresses? Valid values are:
 173
 174  - `short`: 'gwashington <gwashington@example.com>'
 175  - `real`:  'George Washington <gwashington@example.com>'
 176  - `full`: 'gwashington (George Washington) <gwashington@example.com>'
 177
 178 The default is `full`.
 179 EODOC
 180 ));
 181
 182     $mailers_description = $this->deformat(pht(<<<EODOC
 183 Define one or more mail transmission services. For help with configuring
 184 mailers, see **[[ %s | %s ]]** in the documentation.
 185 EODOC
 186       ,
 187       PhabricatorEnv::getDoclink('Configuring Outbound Email'),
 188       pht('Configuring Outbound Email')));
 189
 190     $default_description = $this->deformat(pht(<<<EODOC
 191 Default address used as a "From" or "To" email address when an address is
 192 required but no meaningful address is available.
 193
 194 If you configure inbound mail, you generally do not need to set this:
 195 Phabricator will automatically generate and use a suitable mailbox on the
 196 inbound mail domain.
 197
 198 Otherwise, this option should be configured to point at a valid mailbox which
 199 discards all mail sent to it. If you point it at an invalid mailbox, mail sent
 200 by Phabricator and some mail sent by users will bounce. If you point it at a
 201 real user mailbox, that user will get a lot of mail they don't want.
 202
 203 For further guidance, see **[[ %s | %s ]]** in the documentation.
 204 EODOC
 205       ,
 206       PhabricatorEnv::getDoclink('Configuring Outbound Email'),
 207       pht('Configuring Outbound Email')));
 208
 209     return array(
 210       $this->newOption('cluster.mailers', 'cluster.mailers', array())
 211         ->setHidden(true)
 212         ->setDescription($mailers_description),
 213       $this->newOption('metamta.default-address', 'string', null)
 214         ->setLocked(true)
 215         ->setSummary(pht('Default address used when generating mail.'))
 216         ->setDescription($default_description),
 217       $this->newOption(
 218         'metamta.one-mail-per-recipient',
 219         'bool',
 220         true)
 221         ->setLocked(true)
 222         ->setBoolOptions(
 223           array(
 224             pht('Send Mail To Each Recipient'),
 225             pht('Send Mail To All Recipients'),
 226           ))
 227         ->setSummary(
 228           pht(
 229             'Controls whether Phabricator sends one email with multiple '.
 230             'recipients in the "To:" line, or multiple emails, each with a '.
 231             'single recipient in the "To:" line.'))
 232         ->setDescription($one_mail_per_recipient_desc),
 233       $this->newOption('metamta.can-send-as-user', 'bool', false)
 234         ->setBoolOptions(
 235           array(
 236             pht('Send as User Taking Action'),
 237             pht('Send as Phabricator'),
 238           ))
 239         ->setSummary(
 240           pht(
 241             'Controls whether Phabricator sends email "From" users.'))
 242         ->setDescription($send_as_user_desc),
 243       $this->newOption(
 244         'metamta.reply-handler-domain',
 245         'string',
 246         null)
 247         ->setLocked(true)
 248         ->setDescription(pht('Domain used for reply email addresses.'))
 249         ->addExample('phabricator.example.com', ''),
 250       $this->newOption('metamta.recipients.show-hints', 'bool', true)
 251         ->setBoolOptions(
 252           array(
 253             pht('Show Recipient Hints'),
 254             pht('No Recipient Hints'),
 255           ))
 256         ->setSummary(pht('Show "To:" and "Cc:" footer hints in email.'))
 257         ->setDescription($recipient_hints_description),
 258       $this->newOption('metamta.email-preferences', 'bool', true)
 259         ->setBoolOptions(
 260           array(
 261             pht('Show Email Preferences Link'),
 262             pht('No Email Preferences Link'),
 263           ))
 264         ->setSummary(pht('Show email preferences link in email.'))
 265         ->setDescription($email_preferences_description),
 266       $this->newOption('metamta.public-replies', 'bool', false)
 267         ->setBoolOptions(
 268           array(
 269             pht('Use Public Replies (Less Secure)'),
 270             pht('Use Private Replies (More Secure)'),
 271           ))
 272         ->setSummary(
 273           pht(
 274             'Phabricator can use less-secure but mailing list friendly public '.
 275             'reply addresses.'))
 276         ->setDescription($public_replies_description),
 277       $this->newOption('metamta.single-reply-handler-prefix', 'string', null)
 278         ->setSummary(
 279           pht('Allow Phabricator to use a single mailbox for all replies.'))
 280         ->setDescription($single_description),
 281       $this->newOption('metamta.user-address-format', 'enum', 'full')
 282         ->setEnumOptions(
 283           array(
 284             'short' => pht('Short'),
 285             'real' => pht('Real'),
 286             'full' => pht('Full'),
 287           ))
 288         ->setSummary(pht('Control how Phabricator renders user names in mail.'))
 289         ->setDescription($address_description)
 290         ->addExample('gwashington <gwashington@example.com>', 'short')
 291         ->addExample('George Washington <gwashington@example.com>', 'real')
 292         ->addExample(
 293           'gwashington (George Washington) <gwashington@example.com>',
 294           'full'),
 295       $this->newOption('metamta.email-body-limit', 'int', 524288)
 296         ->setDescription(
 297           pht(
 298             'You can set a limit for the maximum byte size of outbound mail. '.
 299             'Mail which is larger than this limit will be truncated before '.
 300             'being sent. This can be useful if your MTA rejects mail which '.
 301             'exceeds some limit (this is reasonably common). Specify a value '.
 302             'in bytes.'))
 303         ->setSummary(pht('Global cap for size of generated emails (bytes).'))
 304         ->addExample(524288, pht('Truncate at 512KB'))
 305         ->addExample(1048576, pht('Truncate at 1MB')),
 306     );
 307   }
 308
 309 }