Add a setting for selecting SMTP mail encoding

Summary:
Fixes T5956. We changed the default mail encoding to `quoted-printable` to fix delivery via SendGrid via SMTP, but this broke multiple other mailers.

  - Change the default back to 8bit (which works everywhere except SendGrid).
  - Add a configuration setting for selecting `quoted-printable`.
  - Document this issue.
  - Discourage use of SendGrid in documentation.

(IMPORTANT) @klimek @nickz This reverts the `quoted-printable` fix for SendGrid. You will need to adjust your configurations (set `phpmailer.smtp-encoding` to `quoted-printable`) and restart your daemons or mail will get double newlines again.

Test Plan:
  - Sent mail via SendGrid with various `phpmailer.smtp-encoding` settings, saw mail arrive with specified encoding.

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: klimek, nickz, epriestley

Maniphest Tasks: T5956

Differential Revision: https://secure.phabricator.com/D10397

src/applications/config/option/PhabricatorPHPMailerConfigOptions.php

@@ -44,6 +44,23 @@ final class PhabricatorPHPMailerConfigOptions
       $this->newOption('phpmailer.smtp-password', 'string', null)
         ->setMasked(true)
         ->setDescription(pht('Password for SMTP.')),
+      $this->newOption('phpmailer.smtp-encoding', 'string', '8bit')
+        ->setSummary(pht('Configure how mail is encoded.'))
+        ->setDescription(
+          pht(
+            "Mail is normally encoded in `8bit`, which works correctly with ".
+            "most MTAs. However, some MTAs do not work well with this ".
+            "encoding. If you're having trouble with mail being mangled or ".
+            "arriving with too many or too few newlines, you may try ".
+            "adjusting this setting.\n\n".
+            "Supported values are `8bit` (default), `quoted-printable`, ".
+            "`7bit`, `binary` and `base64`.\n\n".
+            "The settings in the table below may work well.\n\n".
+            "| MTA | Setting | Notes\n".
+            "|-----|---------|------\n".
+            "| SendGrid via SMTP | `quoted-printable` | Double newlines under ".
+            "`8bit`.\n".
+            "| All Other MTAs | `8bit` | Default setting.")),
     );
   }
 

src/applications/metamta/adapter/PhabricatorMailImplementationPHPMailerAdapter.php

@@ -13,10 +13,8 @@ final class PhabricatorMailImplementationPHPMailerAdapter
     $this->mailer = new PHPMailer($use_exceptions = true);
     $this->mailer->CharSet = 'utf-8';
 
-    // NOTE: This works around what seems to be a bug in SendGrid, see
-    // D10278. This affects other SMTP mailers too, but as long as they
-    // don't have an opposite bug to SendGrid's bug that should be OK.
-    $this->mailer->Encoding = 'quoted-printable';
+    $encoding = PhabricatorEnv::getEnvConfig('phpmailer.smtp-encoding', '8bit');
+    $this->mailer->Encoding = $encoding;
 
     // By default, PHPMailer sends one mail per recipient. We handle
     // multiplexing higher in the stack, so tell it to send mail exactly

src/applications/metamta/adapter/PhabricatorMailImplementationPHPMailerLiteAdapter.php

@@ -15,7 +15,9 @@ class PhabricatorMailImplementationPHPMailerLiteAdapter
     require_once $root.'/externals/phpmailer/class.phpmailer-lite.php';
     $this->mailer = new PHPMailerLite($use_exceptions = true);
     $this->mailer->CharSet = 'utf-8';
-    $this->mailer->Encoding = 'quoted-printable';
+
+    $encoding = PhabricatorEnv::getEnvConfig('phpmailer.smtp-encoding', '8bit');
+    $this->mailer->Encoding = $encoding;
 
     // By default, PHPMailerLite sends one mail per recipient. We handle
     // multiplexing higher in the stack, so tell it to send mail exactly

src/docs/user/configuration/configuring_outbound_email.diviner

@@ -12,7 +12,7 @@ Phabricator can send outbound email via several different providers, called
 |---------|-------|------|---------|-------|
 | Mailgun | Easy | Cheap | Yes | Recommended |
 | Amazon SES | Easy | Cheap | No | Recommended |
-| SendGrid | Easy | Cheap | Yes | |
+| SendGrid | Medium | Cheap | Yes | Discouraged (See Note) |
 | External SMTP | Medium | Varies | No | Gmail, etc. |
 | Local SMTP | Hard | Free | No | (Default) sendmail, postfix, etc |
 | Custom | Hard | Free | No | Write an adapter for some other service. |
@@ -34,6 +34,11 @@ it to be able to deliver mail. You should receive setup warnings if they are
 not. For more information on using daemons, see
 @{article:Managing Daemons with phd}.
 
+**Note on SendGrid**: Users have experienced a number of odd issues with
+SendGrid, compared to fewer issues with other mailers. We discourage SendGrid
+unless you're already using it. If you send to SendGrid via SMTP, you may need
+to adjust `phpmailer.smtp-encoding`.
+
 = Basics =
 
 Regardless of how outbound email is delivered, you should configure these keys
@@ -83,6 +88,9 @@ 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, strongly consider using Mailgun or Amazon SES instead.
 
+If you experience issues with mail getting mangled (for example, arriving with
+too many or too few newlines) you may try adjusting `phpmailer.smtp-encoding`.
+
 = Adapter: SMTP =
 
 You can use this adapter to send mail via an external SMTP server, like Gmail.
@@ -97,6 +105,9 @@ To do this, set these configuration keys:
   - **phpmailer.smtp-password**: set to your password used for authentication.
   - **phpmailer.smtp-protocol**: set to `tls` or `ssl` if necessary. Use
     `ssl` for Gmail.
+  - **phpmailer.smtp-encoding**: Normally safe to leave as the default, but
+    adjusting it may help resolve mail mangling issues (for example, mail
+    arriving with too many or too few newlines).
 
 = Adapter: Mailgun =