Last modified: June 25, 2025 at 7:10pm

Drupal CMS includes a modern, flexible system for handling email. It’s designed to improve reliability, support branded HTML messages, and connect securely to the email delivery service of your choice. 

This tutorial shows how to set up that system and connect it to an SMTP provider like Gmail, SendGrid, Mailgun, or Amazon SES. As well as how to modify the email templates used to ensure they meet your branding guidelines.

We’ll use Gmail as the mailing service for the step-by-step examples, but the same instructions apply no matter which provider you choose—just update the connection details to match your service.

By the end of this tutorial you'll know how to connect Drupal CMS to an SMTP mail server of your choice, and how to configure the templates Drupal uses when sending emails.

Back to top

Goal

Understand how to set up well-formatted emails and reliable delivery for your Drupal CMS site.

Back to top

How email sending works

Before you get started, it helps to understand what needs to happen for your site to send an email. There are a few moving parts:

  • Some emails are sent automatically by the system; for example, when someone creates an account or resets their password.
  • Other emails are triggered by visitors doing something, like submitting a contact form or completing a checkout.
  • Every message needs a design. You can create templates to style your emails with your branding, colors, and layout.
  • And of course, there’s the actual sending. You can use basic built-in tools, or preferably use a more reliable method by connecting to a trusted mail service like Gmail or SendGrid.

When your site sends an email, here’s what happens:

  1. The content gets assembled—subject line, body text, and any personalized info.
  2. A design template gets applied so the email looks good in someone’s inbox.
  3. The system decides how to send it and hands it off to a mail service.
  4. That service sends the email through your chosen provider.

Drupal CMS includes pre-made templates for common messages, and a fallback for everything else. If you add new features or modules later, you can easily create matching templates to keep everything consistent.

Back to top

Do I need to configure SMTP?

Yes—if you want your site’s emails to actually reach people. The built-in option (using PHP’s mail function) might work on some servers, but it's often blocked or ignored by modern hosting environments. Even when it works, the emails can easily land in spam folders. Configuring SMTP connects your site to a real email service that’s designed to deliver messages reliably, securely, and with fewer issues.

Back to top

Check for integration modules first

Some email delivery services, like SendGrid or Mailgun, offer their own integration modules for Drupal. These are often the easiest and most reliable way to set up email, since they may include added features like click tracking, deliverability logs, or template syncing. Before configuring SMTP manually below, it’s worth checking whether your provider offers an integration module that works out of the box.

Back to top

Configure Drupal CMS to send emails via SMTP

Let's walk through how to configure your site to send email using SMTP. We'll use Gmail as the example SMTP provider, however you should be able to use any SMTP server so long as you know the connection details.

Step #1: Gather your SMTP connection information

Google requires that you create an App Password in your Google account:

  1. Visit https://myaccount.google.com/security.
  2. Turn on 2-Step Verification (if it’s not already enabled).
  3. Visit https://myaccount.google.com/apppasswords.
  4. Choose an App name such as “Drupal CMS”..
  5. Click Generate.
  6. Copy the generated password—you’ll use it as your SMTP password.

Step #2: Configure your SMTP credentials in Drupal

  1. In the Drupal CMS admin interface, go to Configuration > System > Drupal Symfony Mailer Lite (/admin/config/system/symfony-mailer-lite/transport).
  2. Choose SMTP from the Transport type select list and then press the Add transport button.
  3. Under SMTP settings, enter:
    • Label: Gmail SMTP
    • User name: your full Gmail address
    • Password: the 16-character App Password from Google created above
    • Host name: smtp.gmail.com
    • Port: 587
    • Perform TLS peer verification: On
  4. Save the configuration.

Step #3: Send a test email

  1. On the same settings page navigate to the Test tab.
  2. Enter an email address to test delivery.
  3. Press the Send test email button and confirm the email arrives in the inbox.

Once you’ve confirmed everything is working, your site is now using Gmail's SMTP servers to send mail. You can swap in any other SMTP provider—just replace the host, port, and credentials with their values.

Step #4: Set SMTP as the default mailer

To send all emails via SMTP navigate to Configuration > System > Drupal Symfony Mailer Lite (/admin/config/system/symfony-mailer-lite/transport). Locate the SMTP option in the list and choose Set as default from the Operations menu.

⚠️Warning: See the section below about handling email on development environments.

Back to top

Configuring email templates

With SMTP delivery ready, the next step is making sure every message looks the way you want. Drupal CMS provides an Email templates dashboard at Structure > Email templates (/admin/structure/email-templates/templates) that lets you preview, duplicate, design, and test HTML email layouts.

Email templates consist of HTML for layout, text, and placeholders (known as tokens) that represent information dynamically added to the email by Drupal CMS.

Below are details covering how to perform common email template related tasks.

Browse existing templates

  1. On the Templates tab you’ll see ready‑made layouts—for example Password reset and User account created.
    Table showing a list of email templates in Drupal CMS for different user account events like activation, password recovery, and approval.
  2. Choose Preview template from the Operations menus to see how a template renders in a typical inbox.
    Preview of an account activation email template showing headers, HTML body, and plain text fallback.

Edit the design and content of a template

Note: Using the UI you can edit the body of an email template. If you wish to change the HTML layout, header, footer, and colors, you’ll need to edit the associated Twig template file(s) and CSS. Start by creating a new theme that extends the provided Easy Email Theme. Then update the Easy Email configuration to use your new theme.

To modify the body content and layout of an email:

  • Locate the template you wish to edit and choose Edit template from the Operations menu.
  • Use the provided form to modify the template.
  • Click the Browse available tokens link under the textarea for editing the email’s content to see a list of dynamic content items that can be inserted into the template.
    Section of email template form showing the link to open the token browser UI.
  • The Email storage section of the form allows you to control whether emails sent using this template are logged, and if so for how long.
    Section of email template form showing settings for email storage with options to save and delete emails after a specified number of days.

Assign the template to an email (Overrides)

Table showing a list of email overrides with associated machine names and edit options.

Templates by themselves don’t send mail—they need an Override that tells Drupal when to use them:

  1. Switch to the Overrides tab.
  2. Click Add email override.
  3. Pick an Email to override (for example User: Welcome) from the drop‑down. Every system generated email has a unique ID.
  4. Choose the template you just created.
  5. Save. From now on, that system email will use your custom template.

Tip: If a new module introduces an email that you haven’t customised yet, Drupal falls back to a default HTML template so your branding remains intact.

Back to top

Viewing email logs

Drupal CMS records each message it attempts to send (this is configured per-email template) in an Email log located at Reports > Email log (/admin/reports/email).

Admin page with table showing the email log report showing a sent message labeled ‘Default’ with recipient email, date, and status.

Use the Email log to:

  1. Confirm delivery attempts – Quickly see if Drupal tried to send a message you’re expecting.
  2. Debug issues – If status shows “Failed,” click View to review error details and compare with your SMTP provider’s logs.
  3. Verify template changes – After editing a template, send a test email and use the log’s View link to preview the final HTML.

The log automatically purges older entries based on your site’s log‑rotation settings, so consider exporting important records if you need long‑term auditing.

Back to top

Handling development environments

During development, you usually don't want your site sending real emails to real users. Not only can that be confusing or risky, it can also lead to deliverability issues if test messages are flagged as spam. Instead, you can configure your local or staging environments to send messages to tools like Mailpit so you can review emails without sending them.

Note: If you’re using Drupal CMS locally with DDEV this should be set up already. Check the sites/default/settings.ddev.php file to review.

You can override the configuration for the SMTP mailer either via an environment specific settings.php file or using a module like Configuration Split.

The example (from settings.ddev.php) below demonstrates changing the SMTP transport configuration to send to the Mailpit server included with DDEV by hard-coding it into the environment’s variables:

 

// Override drupal/symfony_mailer default config to use Mailpit.
$config['symfony_mailer.settings']['default_transport'] = 'sendmail';
$config['symfony_mailer.mailer_transport.sendmail']['plugin'] = 'smtp';
$config['symfony_mailer.mailer_transport.sendmail']['configuration']['user'] = '';
$config['symfony_mailer.mailer_transport.sendmail']['configuration']['pass'] = '';
$config['symfony_mailer.mailer_transport.sendmail']['configuration']['host'] = 'localhost';
$config['symfony_mailer.mailer_transport.sendmail']['configuration']['port'] = '1025';

 

Another option is to add a new Null transport option via the UI and set that as the default. Then configure just your production site to use the SMTP transport configuration.

Back to top

Next steps

  • Verify the site‑wide email (Configuration > System > Basic site settings (/admin/config/system/site-information)). The email address shown under Site details is the address that will be used to send emails by default unless overridden by the specific template.
  • Test common workflows (like password reset or new account confirmation).
  • Monitor deliverability with your mail service provider’s dashboard (bounces, complaints).
  • Optional: Mail System granularity — map certain modules (e.g., Commerce) to a different mailer if needed.
Back to top

Wrap-up

Drupal CMS can be configured to deliver fully‑themed HTML email through any SMTP or API transport. Switching to an SMTP provider to deliver both system created (e.g. password reset) and user generated (e.g. contact form) emails ensures reliable delivery. And using the email template system ensures the messages your users receive are on-brand and attractive.

Back to top

Additional resources

Learn more about the modules used in Drupal CMS's modern email system:

  • Easy Email: Provides the interface for managing email templates and overrides.
  • Symfony Mailer Lite: Adds SMTP support using Symfony Mailer.
  • Mail System: Lets you assign different mailer and formatter plugins to various parts of Drupal.
Back to top