How to Configure Drupal Webform Emails with SMTP and Mail System | iBuild.PH Knowledgebase

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:

• Webform (drupal.org/project/webform)
• Mail System (drupal.org/project/mailsystem)
• SMTP Authentication Support (SMTP) (drupal.org/project/smtp)

Install them using Composer:

Enable the modules:

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

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

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

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:

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:

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

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

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.