Sending reliable email notifications from Drupal is essential for contact forms, service inquiries, and other user submissions. This guide explains how to properly configure Drupal 10 and 11 to send HTML emails using Webform handlers, the Mail System module, and optionally the SMTP module for authenticated delivery.

This configuration ensures that all Webform submissions are formatted, delivered securely, and reach the intended recipients.

1. Modules required

Before configuring email delivery, make sure the following modules are installed and enabled:

Install them using Composer:

composer require drupal/webform drupal/mailsystem drupal/smtp

Enable the modules:

drush en webform mailsystem smtp -y

2. Configure the SMTP module

If you plan to use a third-party mail server such as Microsoft 365, Gmail, or another authenticated SMTP provider, configure the SMTP module.

Go to:
Configuration → System → SMTP Authentication Support

Setting Example
SMTP server smtp.office365.com or smtp.gmail.com
SMTP port 587
Use TLS encryption ✔ Checked
Username your email address
Password your app or mail password
E-mail from address same as above
E-mail from name your company name
Allow to send e-mails formatted as HTML ✔ Checked

Example for Microsoft Outlook SMTP mail sending

configure-SMTP-drupal-module-for-outlook-webmail

💡 Make sure your web server allows outbound connections on port 587 or the SMTP port required by your mail provider.

3. Configure the Mail System module

Go to:
Configuration → System → Mail System

Use the following recommended working configuration for Webform-based emails:

Setting Value
Default Mail System
Formatter Webform PHP mailer
Sender Webform PHP mailer
Theme Default
Module-specific configuration
Module: Webform Formatter: Webform PHP mailer
Sender: Webform PHP mailer
Module: Contact (optional) Formatter: Webform PHP mailer
Sender: Webform PHP mailer

✅ Why this works

  • Uses Webform’s internal mailer for clean HTML rendering.

  • Maintains HTML structure in emails.

  • Compatible with both the PHP mailer and SMTP sender.

drupal-configure-mail-system-settings-for-webform

4. Set up or update your Webform handler

Go to:
Structure → Webforms → [Your Webform] → Emails / Handlers

Click Edit or Add Email Handler and configure:

Setting Example Value
To Recipient email address
BCC Optional additional recipients
From [name] <no-reply@yourdomain.com>
Reply to [email]
Subject Service inquiry or contact form submission
Send email as HTML
Send when Completed

Sample:

configure-drupal-webform-handlers-for-email-sending

5. Add custom HTML message and submission data

In the Message field of your Webform handler, you can include your own HTML layout and submission tokens.

Example using the custom Twig formatter in the handler Body settings:

<p>Thanks for your message. Our team will get back to you shortly with any additional details they might need.</p>
<p>Submitted on {{ webform_token('[webform_submission:created]', webform_submission, [], options) }}</p>
<p>Submitted by: {{ webform_token('[webform_submission:user]', webform_submission, [], options) }}</p>
<p>Submitted values are:</p>
{{ webform_token('[webform_submission:values]', webform_submission, [], options) }}

📌 The token [webform_submission:values:html] automatically includes all submitted form fields with HTML formatting.

6. Test your configuration

  1. Visit the page containing your Webform.

  2. Submit a test message.

  3. Check the recipient inbox or spam folder.

  4. Review logs at /admin/reports/dblog if no message is received.

If you receive the email with proper formatting (paragraphs, links, line breaks), the configuration is working.

7. Optional: Combine HTML formatting with SMTP delivery

If you want to use SMTP for the actual sending process while keeping HTML formatting handled by Webform, adjust the Mail System settings:

Setting Value
Formatter Webform PHP mailer
Sender SMTP Mailer

This ensures Webform continues to format emails as HTML, while SMTP handles delivery securely through your chosen mail server.

8. Troubleshooting

Emails appear as plain text:
– Ensure the handler is set to send as HTML.
– Verify the Mail System formatter is Webform PHP mailer.

Emails not sending:
– Double-check SMTP credentials and ports.
– Test using the PHP mailer to isolate SMTP issues.

Emails duplicated or inconsistently formatted:
– Avoid conflicting Mail System configurations across modules.

Summary

Module Purpose Recommended Plugin
Webform Manages form creation and submission handlers Webform PHP mailer
Mail System Controls mail formatting and sending logic Webform PHP mailer
SMTP Provides authenticated email delivery SMTP Mailer (optional)

This combination provides a stable and flexible way to send HTML-formatted emails from Drupal Webforms, compatible with both native mail and SMTP-based systems.