When you're theming a Drupal Commerce site, you shouldn't forget to style the emails your store sends. The primary use case is the checkout completion email that includes the customer's receipt, but there may be others depending on your feature set and customizations (e.g. dunning emails for recurring subscriptions).

Commerce Core provides a basic, table based template that you'll want to either replace or at least ensure is styled by your theme to reflect your branding. (Find it in the order module's templates directory, commerce-order-receipt.html.twig.) However, without adding the capacity to properly send HTML email from your site, it's going to look like a jumbled mess in your customer's inbox.

We've long recommended Swift Mailer for formatting and sending HTML emails from Drupal Commerce. Symfony announced the project's deprecation late last year, recommending folks switch to using the 3 year old Symfony Mailer instead after they brought it up to full feature parity with the Swift Mailer library.

Fortunately, there's a module for that!

Drupal's Symfony Mailer module integrates the library and provides a "backwards compatibility" module that ensures the module can serve as a drop-in replacement for the old Mail System module the Swift Mailer module depended on. Making the switch in my local testing was as simple as:

1. Uninstall the Swift Mailer module.
2. Uninstall the Mail System module.
3. Add the Symfony Mailer module to my project (using Composer).
4. Install the Symfony Mailer and Symfony Mailer Back-compatibility modules.
5. Define a transport type. (I develop locally with ddev, so I added an SMTP transport using 127.0.0.1 as the host, port 1025, and no username / password.)
6. Make that your default transport.

And that's it! After taking the above steps, my email receipts showed up as properly formatted HTML emails. If you're also developing locally using ddev, remember you can review all email sent by your site in MailHog on port 8026 (i.e. by navigating to https://example.ddev.site:8026).

The Symfony Mailer module offers a variety of "policy" options you may need to review depending on how you've customized email on your site. You can use these policy options to alter properties of different emails, such as setting a custom reply-to address for your receipt emails.

The module is still in active development with only an alpha release, so make sure to test it fully in a development environment before deploying to production. Leave a comment with any tips you glean from your own implementation!