Set up email sending¶

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

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.

Emails will send using only the default settings, but the most reliable method of sending email is to connect it to an SMTP provider such as Gmail, SendGrid, Mailgun, or Amazon SES.

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.

Do I need to configure SMTP?¶

No, but it's a good idea, especially if your site relies on email sending reliably. 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, and the emails can easily land in spam folders. Configuring SMTP connects your site to an email service that’s designed to deliver messages reliably and securely.

Check for integration modules¶

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.

• Learn more about adding functionality with modules

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. When generating an App Password use the Google account matching the email address you want to send emails from. For most people this should match the email address on the Configuration > System > Basic settings page:

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.

Handling development environments¶

During development, you may want your site sending real emails to real users. 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.

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.