[META] Adopt the symfony mailer component

Problem/Motivation

• The current mail system dates from many years ago and only supports plain text email and the PHP transport.
• There are contrib modules that extend this, but they are significantly hampered by the current interfaces which were designed only for plain text. We end up code duplication in each module sending HTML mail as they attempt to fill the missing function in their own way.
• Sending emails in the modern world is a complex task. The Drupal community are currently maintaining this code, which is inefficient. There is little ongoing development so the code is more outdated and lower quality.

Advantages of Symfony Mailer include HTML mails, file attachments, embedded images, 3rd-party delivery integrations, load-balancing/failover, signing/encryption, async sending and more. Other 3rd-party libraries add capability for CSS inlining and HTML to text conversion.

Proposed resolution

Stage 1: Create a @Mail plug-in based on Symfony mailer.

In this part we integrate Symfony mailer as far as possible within the existing mail system. By doing so we can make some clear advances without tackling to complexity of creating a new mail system. This allows sites to start benefitting from new features, and makes the eventual new mail system development easier because parts have already been done.

• #3165762: Add symfony/mailer into core Add the symfony/mailer component as a composer dependency to Drupal core. Additionally make all supported Symfony mailer transports accessible via a simple mail plugin which can act as a drop-in replacement for the existing php mail plugin.
• #3379794: Add symfony mailer transports to Dependency Injection Container
• #3384844: [PP-1] Add security checking for Symfony Mailer transports
• #3392879: Add support for HTML email to Symfony Mailer plug-in
• #3392881: Deprecate the PHPMail plug-in in favour of symfony mailer
• #3395814: Framework for testing Symfony Emails
• #3395815: Page to send a verification email

Stage 2: Create a new mail system based on Symfony mailer.

Similar in concept to Drupal Symfony Mailer. module, simplified and without any of the "overriding" code (which is for 'upgrading' emails sent by Core and other modules to be full modern HTML).

• #3380041: Create new mailer service based on symfony which creates a new API with direct access to the power of Symfony Mailer, plus integration into Drupal mechanisms, including: theme/template/render, multi-language, CSS libraries, configuration, plug-ins, hooks, and logging.
• #3380269: Create a plug-in system to build emails with Symfony Mailer
• #3380273: Create a system for configurable emails in Symfony Mailer
• #3380470: Migration strategy for moving to Symfony Mailer
• #3380472: Create a BC mapper for MailManager to convert to Symfony Mailer
• #3380476: Change core modules to use Symfony Mailer

Stage 3: Support new mail system in contrib.

Work with contrib to ensure adoption

• Migrate implementations of hook_mail() to use new Mailer API
• Migrate implementations of hook_mail_alter() to new events similar to MessageEvent.

Stage 4: remove the old mail system

• Deprecate then remove MailManager and @Mail plug-in system.
• Deprecate then remove use of the old mail system in core modules.
• Deprecate then remove the old API hook_mail() and hook_mail_alter().

The last one could be done one Drupal major version after the others as it provides a big increase to BC with a small amount of code.

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet

#### Original Issue Summary ####

What does Symfony Mailer provide that is better than the current mail system

Swiftmailer simplifies means integrating email communications within Drupal. The current mail system only supports plain text email and one transport method.

Swiftmailer provides plain text and HTML content types and multiple transport methods. It has a pluggable system that allows it to be extended, like Twig.

Currently we manage our own plugin system for mail that provides a default PHP `mail()` integration. Contributed modules must then provide integration with SMTP, sendmail, or others. This also means integrations for Sendgrid and Mandrill must require the SMTP module or write their own mail plugin.

What new features would Swiftmailer enable that we currently don't have?

Swiftmailer would immediately allow Drupal to send email over SMTP, Sendmail, PHP, or any other possible transport method. More can be read here: http://swiftmailer.org/docs/sending.html.

This also means users can immediately integrate with services like SendGrid and Mandrill out of the box with Drupal.

* SendGrid: https://sendgrid.com/docs/Integrate/Code_Examples/v2_Mail/php.html
* Mandrill: https://mandrill.zendesk.com/hc/en-us/articles/205582157-How-to-Send-wit...

One need, especially in the e-Commerce realm, is HTML enabled emails for rich customer experiences. Allowing Drupal to send HTML based emails out of the box will improve the experience built on top of Drupal for customers interacting with it.

Why is Swiftmailer the best library for that? Are there alternatives?

Swiftmailer is an open source library that is part of SensioLabs. Drupal currently incorporates Twig and many Symfony components, all of which are part of SensioLabs. This makes Swiftmailer highly qualified and further brings together the Drupal communities and PHP community at large collaborating with SensioLab libraries.

There is PHPMailer (https://github.com/PHPMailer/PHPMailer), however it is not pluggable like Swiftmailer, and may be harder to customize than Swiftmailer.

What are the drawbacks of integrating Swiftmailer?

We have to handle deprecation of Drupal's messy mail system (Mail plugins, hook_mail.) We would probably have to deprecate the SMTP module and Mailsystem module.

I can't come up with any drawbacks.

Next steps

• Use this issue as the plan/meta for integrating Swiftmailer
• Get the library in core
• Have core's php_mail use Swift_Transport_MailTransport instead of mail() directly
• Use a library like html2text/html2text to deprecate methods in \Drupal\Core\Mail\MailFormatHelper
• If an email specifies its content type as text/html respect that and allow it to send
• Find a way to expose settings like the Swiftmailer module for configuring transport options

Original issue summary

Might be a good first step in de-WTF-ing our mail system.