Replace Swift Mailer with Symfony Mailer for HTML email

Developer Desk

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 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

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!


Submitted by jb (not verified) on Tue, 04/05/2022 - 08:03

thanks for explaining Symfony Mailer. This project is not covered by the security advisory policy. (on the module page)
you don`t have any security concerns using it?

Submitted by Ryan Szrama on Mon, 04/18/2022 - 19:13

In reply to by jb (not verified)

Not particularly. The fact it isn't covered is primarily due to it not having a full release yet. The security team works on behalf of projects that have full tagged releases. However, in this case, the meat of the project - the actual mailer library itself - is a Symfony maintained project that has been stable for a long time. That's not to say you shouldn't proceed with caution, but we don't see any particular risk in using the module at present.

(Bear in mind that even projects "covered" by the policy can still have security issues; it's just that there's a process by which the security team oversees disclosure and communication about vulnerabilities. Great question, though!)

Submitted by Eric Guerin (not verified) on Fri, 06/17/2022 - 19:00

I'm not sure why the article mentions removing the mail system, isn't that module designed to be the go between Drupal and any other Mail related module? Seems like Symfony Mailer would support that I would suspect?

Submitted by Michael Lechasseur (not verified) on Wed, 03/29/2023 - 18:58

I wasn't able to uninstall swiftmailer from the drupal UI.

The site was created in Drupal 8 and the composer.json made reference to:
"drupalcommerce/commerce_base": "dev-8.x-1.x",

Despite making a "composer update drupalcommerce/commerce_base" the swiftmailer requirement was still included. But forcing an upgrade to commerce_base "9.x" added symphony mailer and removed swiftmail and mailsystem but the composer update broke my site because the modules hadn't been uninstalled from the UI.

I reinstalled swiftmail and mailsystem, then uninstalled from the Drupal UI, then removed with Composer.

That seems to have worked.

Submitted by Ryan Szrama on Wed, 05/31/2023 - 14:00

In reply to by Michael Lechasseur (not verified)

Ahh, yeah, thanks for sharing. Once we launched Commerce Kickstart as our preferred starting point for new sites, I suppose we forgot about the commerce_base project. Will put an issue in our tracker to resolve that somehow.

Add new comment