Drupal email delivery with SMTP and Symfony Mailer

Drupal email delivery with SMTP and Symfony Mailer: what the integration does

When password resets, form notifications and workflow emails from Drupal land in spam or never leave the server, the supported fix is to route Drupal's outgoing mail through an external SMTP server or transactional email service instead of the web server's local mail function. Two contributed modules do this on Drupal.org: the SMTP Authentication Support module, which sends mail through an external SMTP server or email service, and Mailer Plus (DSM+), which builds on Symfony Mailer. Both are derivative works of Drupal licensed under GPL-2.0-or-later, so neither carries a licence fee, and the choice between them depends on your Drupal version and how your mail is architected.

In practice, the integration changes where Drupal hands off each message. Core mail calls pass through the module, which authenticates to the relay, applies the sender and transport settings you define, and delivers the message. The SMTP module is the long-standing option and is widely used across Drupal sites. Mailer Plus is the newer approach, and it relies on Symfony Mailer transports, so it fits better when you want per-module sender rules, multiple transports or templated HTML mail handled in one place. Confirm the exact Drupal versions each module supports on its project page before you commit, since the Mailer Plus 2.0.2 release supports Drupal ^10.3 or ^11 according to its project listing.

The choice of relay is a decision for your security and operations teams, not only for the Drupal team. You need to know which service will send mail for your domain, who holds the SMTP credentials and where they are stored, and whether the relay accepts mail from the sending addresses your site uses. Those answers feed directly into the SPF and DKIM work covered later in this page. Ask your provider and your own infrastructure owners to confirm sending limits, logging and retention before go-live, because those settings determine what you can prove when a message is disputed.

What you need before configuring Drupal mail

Mail delivery depends on the Drupal version, the PHP runtime, a sending provider and DNS records that all have to agree. Confirm these five items first, because a gap in any one of them tends to surface later as messages that never arrive or land in spam folders.

Drupal version and PHP runtime

Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, according to the Drupal.org PHP requirements page. Check the PHP version on every web node, not only on the build server, because a mismatch can pass staging and fail in production. Drupal 7 sites must migrate to a supported version before this integration applies, since the SMTP and Mailer Plus modules target current Drupal releases.

Mailer Plus version compatibility

Mailer Plus (DSM+) 2.0.2 supports Drupal ^10.3 or ^11, so confirm your core version against that constraint before you add the module with Composer. Record the exact version in your lock file and plan upgrades alongside core upgrades, since a core move can require a newer module release. Ask your team whether they will use the Symfony Mailer based module or the classic SMTP module, because that choice decides which configuration screens and transport settings you document.

Relay or transactional provider account

Open an account with an SMTP relay or transactional email service and generate dedicated SMTP credentials for the Drupal site, not shared personal logins. Ask the provider which hostnames, ports and encryption modes it supports, whether it enforces per-key sending limits, and how it reports bounces and complaints. Store the username and password in your secrets manager so they stay out of exported configuration.

DNS access for SPF and DKIM

Someone on your team needs authority to publish TXT records for the sending domain, because SPF and DKIM are what receiving servers check when deciding whether your messages are genuine. Confirm with the provider which DKIM selector it signs with and which include statement it needs in the SPF record. Also confirm whether the provider sends from shared IP addresses or from a domain you own, since that determines how much of the reputation is yours to protect.

Test mailbox and sending domain

Prepare at least one external mailbox that you control, with access to the full message headers and authentication results. Use it to verify that messages pass SPF and DKIM and that the From address matches the domain you signed for. Agree on a sending address such as a no-reply address on your primary domain, and confirm that the mailbox and the sending address exist before testing begins.

Outbound sender and migration status

Confirm with your provider and network team which outbound IP addresses or sending domains will carry Drupal mail, including any failover relay. If the site is still on Drupal 7, its mail path cannot be configured through this integration until the site is migrated. Record the sending owner, the contact for bounce reports and the change process for IP or domain changes, so the mail path stays stable after launch.

How to configure SMTP or Mailer Plus in sequence

This sequence takes a Drupal site from an unreliable default mail path to a configured transport that sends authenticated, traceable messages from every entry point, with each step confirmed before the next begins.

Choose the module by Drupal version and transport needs
The team that owns the site selects between the SMTP Authentication Support module and Mailer Plus (DSM+) before any code changes. The SMTP module is widely used across many Drupal sites, while Mailer Plus 2.0.2 supports Drupal ^10.3 or ^11, so confirm your core version first and check that the chosen module's compatibility matches it. Record which transport you need, such as an SMTP relay or a transactional email API, and whether you need HTML templates. The output is a short decision note naming the module, its version constraint and the transport type. You know this step is done when the Drupal version, module and provider are written down together and reviewed by the person who owns DNS.
Install the module through Composer
A developer adds the chosen module to the project with Composer, so the version is pinned in composer.json and the lock file, then enables it with Drush or the admin interface. Because Drupal sites are built and released through Composer in most setups, this keeps the mail module in the same review and deployment path as core and other contributed projects. Commit the lock file change and deploy it to a non-production environment first. You know this step is done when the module appears in the enabled module list on every environment and the site status page shows no missing dependencies.
Create the sending domain and credentials at the provider
The team responsible for DNS and the mail provider create a sending domain or subdomain, then generate SMTP or API credentials dedicated to this site. Use a separate sending identity for transactional mail rather than a personal mailbox, and limit the credential to sending only. Ask the provider which hostnames, ports and encryption modes it supports, and confirm them in writing rather than copying examples. The output is a sending domain, a credential set and the DNS records the provider requires. You know this step is done when the provider's console shows the domain as verified or pending only for DNS records you are about to publish.
Configure the transport and store credentials outside the database
A developer enters the host, port, encryption and authentication settings in the module configuration, and keeps the password out of the database and version control. Store the secret in an environment variable, a secrets manager or a settings file excluded from the repository, and reference it from configuration. Confirm the port and encryption pairing with the provider, since mismatches are a common cause of failed sends. The output is a working transport configuration with no plain-text secret in exported configuration. You know this step is done when a configuration export contains the host and username but no password, and the site can connect to the relay from the application server.
Set the default From address and name
The site owner and the developer set a default sender address and display name that belong to the verified sending domain. Make sure the From address matches the domain that DNS will authenticate, because mismatched domains weaken SPF and DKIM alignment later. Decide whether individual modules may override the sender, and document that decision so forms and workflows do not send from unverified addresses. The output is a single documented default sender. You know this step is done when a test message's From header shows the expected name and address on the verified domain.
Send test messages from cron, queues and form submissions
The developer triggers test mail from the paths that matter in production: a user registration or password reset, a scheduled cron job, a queued worker and a Webform submission notification. Each path can run under different permissions and processes, so a single successful test is not enough. Check the Drupal logs and the provider's delivery log for each message, and note any path that falls back to PHP mail. The output is a short test log listing each trigger, its result and the provider message ID. You know this step is done when every path produces a delivered message in the provider log and no entries show errors in the Drupal log.
Verify DNS and inbox placement
The team that owns DNS publishes the SPF and DKIM records the provider supplied, then confirms that SPF and DKIM pass for the From domain in a received message's authentication headers. Confirm that the SPF and DKIM domains align with the From domain, and check whether the provider expects a DMARC policy to be published. Send test messages to several mailboxes you control, including common providers used by your audience, and review where they land. Ask the provider and your security team which DMARC policy level to start with before changing it. The output is a verified set of DNS records and recorded header results. You know this step is done when a received message shows passing SPF and DKIM results aligned with the From domain, and the placement checks show inbox delivery for your test mailboxes.

SMTP module or Mailer Plus: how to choose

The choice between the SMTP Authentication Support module and Mailer Plus (DSM+) comes down to how much of your mail handling you want to control inside Drupal and how much you are willing to rebuild if the module changes. The SMTP module is the long-established option: it sends Drupal's mail through an external SMTP server or email service, and its project page reports use on about 142,532 sites. Mailer Plus is built on Symfony Mailer, which handles mail as structured messages, and its 2.0.2 release supports Drupal ^10.3 or ^11. Start by listing what your site must do, then check each project page for current coverage rather than assuming the two offer the same features.

Compare the features your mail flows actually need. Ask whether you need HTML templates managed in Drupal, whether editors will send mail with attachments generated from content, and which transport options your relay supports, such as authenticated SMTP, specific ports or a transactional API. Confirm each of these on the project page for the release you will install, because template handling and transport support change between releases and may differ between the two projects. Also confirm how each project handles per-message settings, such as sender addresses, so that your SPF and DKIM setup covers every sender your site uses.

Treat the choice as a decision you record and can revisit. Pin the module versions you test, keep a short list of the mail types your site sends (account, password reset, workflow notifications, form confirmations), and run one test send per type through the candidate module and your relay before go-live. Plan for upgrades: both projects follow Drupal core releases, so the module you choose will need compatibility checks at each core upgrade. Ask your implementation partner or internal team to document the chosen module, its configuration and the test results so the decision survives staff changes.

HTML templates and sender identity by audience

Content teams edit the words people receive: account notices, password resets, form confirmations and workflow alerts. In a well-scoped build, they change subject lines and body text through an administrative interface, with tokens such as the recipient name or a link filled in automatically. They should not need to touch markup, and they should not be able to change which address the mail appears to come from.

Editable copy: Confirm which messages are editable in the interface and which are fixed in code, such as one-time login links.
Token use: Agree on the tokens each message may use, and document what each one renders.
Preview and test sends: Require a preview and a test send to a controlled mailbox before a changed message goes live.
Language variants: If the site is multilingual, decide who translates each message and who signs off.
Change records: Keep a log of wording changes, since support teams often need to explain what a user received.

Before build, ask the content owner to list every automated message the site sends and mark which ones they will edit themselves.

Which Drupal mail settings map to relay and DNS settings

This table maps the Drupal mail fields you set on the site to the sending domain, envelope and DNS records your relay or transactional email provider expects. Read each row as a handoff: the Drupal value is set by your site team, while the provider value and DNS record are usually issued or confirmed by the email provider and published by whoever controls your domain's DNS.

Drupal setting	Relay or DNS setting	Who owns it
Site mail (system.site mail address)	Sending domain and From address domain must match a domain verified with the provider	Site owner sets the address; domain owner verifies the domain
From name (module or site mail From name)	Display name on the message; does not affect SPF or DKIM alignment	Site owner or marketing
Reply-to address (per message or module setting)	Reply-to header passed through the relay; confirm the provider keeps it unchanged	Site owner; provider confirms pass-through
Mail system key per module (for example, the module's mail key in the mail system configuration)	Routing to the chosen transport, so transactional and bulk messages can use separate credentials or streams	Developer who configures the mail system mapping
Envelope sender (return-path, set by the relay)	Return-path domain used for SPF checks and bounce handling	Provider sets it; domain owner confirms the CNAME or SPF record
DKIM selector and signing key	DNS TXT or CNAME record the provider asks you to publish for signing	Provider issues; DNS administrator publishes
SPF include for the provider	A single SPF record for the domain that includes the provider's sending hosts	DNS administrator; only one SPF record per domain is valid
DMARC policy and reporting address	DMARC record that requires SPF or DKIM alignment with the From domain	Security or email team; confirm report handling before tightening policy

Protecting credentials, sender identity and mail content

Mail from a Drupal site carries credentials, a sender identity and personal data, and each one is an attack or privacy surface. The cards below cover where secrets live, how the relay is locked down, how the From domain is authenticated, and how little personal data the messages and logs should keep.

Keep SMTP credentials out of exports

Store the relay username and password in environment variables or a secrets manager, then reference them from settings.php or the mail transport DSN. Configuration exports are committed to Git and copied between environments, so a password placed in the synced configuration spreads to every developer machine and backup. Check that config/sync contains no SMTP password and that rotating the credential requires no code change.

Scope relay access tightly

Restrict the relay to the addresses of your web servers through IP allow lists, and issue a separate API key per site or environment where the provider supports scoped keys. A key that can send from any domain is a risk if it leaks. Ask your provider which permissions a sending key carries and whether it can be limited to specific sender domains.

Align SPF and DKIM with the From domain

The From address on Drupal's site email, such as the one set in the site information or mail system settings, must belong to a domain you control and that domain's SPF record must include your relay. DKIM signing must use a selector on that same domain. Alignment between the From domain and the authenticated domains is what receiving servers check, so a relay that signs for a different domain can pass one test and still fail DMARC.

Publish DMARC after monitoring

Begin with a DMARC record set to monitor only, collect aggregate reports for a period that covers your normal notification cycles, and confirm that every legitimate Drupal sender passes alignment. Move to quarantine or reject only after the reports show no unexpected sources. Tighten the policy too early and password reset or workflow emails from the site may be silently dropped.

Prevent open relay behavior

The relay must accept mail only from authenticated Drupal servers and must not forward messages for arbitrary senders or recipients. Test from an outside network that the relay refuses unauthenticated submission and unauthorized recipients. An open relay can be abused for spam under your domain, which damages sender reputation and can get the domain blocklisted, affecting every system that sends mail.

Minimize personal data in messages

Notification bodies should carry a link to the content, not the content itself, and should avoid health, financial or case details wherever the message could be read on a shared device or forwarded. Review each template and each Symfony Mailer or SMTP module setting that adds fields to the message. Agree with your privacy team which data classes may appear in email before the templates are built.

Set mail log retention deliberately

Delivery logs usually record recipient addresses, subjects and timestamps, which are personal data. Decide whether recipients are logged at all, how long logs are kept, who can read them and where they are stored. Confirm with your provider how long it retains message metadata, and align the site's log retention and backup policy with that decision.

Why Drupal email fails or lands in spam

This table lists the failures teams most often see with Drupal email, the likely cause of each and a check that confirms the cause. Read it from the symptom column down: find the message behaviour you are seeing, run the check, then apply the fix before changing anything else.

Symptom	Likely cause	Check to run	Fix
Messages are not sent at all	Queued mail is never processed because cron or the queue worker is not running, or the SMTP port and TLS mode do not match the relay	Confirm cron runs on schedule and the mail queue is draining; test the relay host and port with a plain connection from the web server	Restore cron or queue processing, then set the port and encryption mode (STARTTLS or implicit TLS) to match the relay's documentation
Authentication is rejected by the relay	Wrong username or password, an API key used where an SMTP password is expected, or the sending address is not approved for the account	Review the relay's SMTP log and the Drupal watchdog or log entries for the SMTP error code; confirm the sender is a verified address or domain	Rotate or correct the credentials in the secrets store, and verify the From address with the relay before retrying
Messages land in spam	SPF or DKIM does not pass for the domain in the From header, or the envelope and From domains differ, so DMARC alignment fails	Send a test message to a mailbox that shows authentication headers and read the SPF, DKIM and DMARC results	Publish the relay's SPF include and DKIM keys for the sending domain, then confirm alignment with the From domain
Wrong From address appears on messages	Site-wide mail settings or the module's default sender were not updated after a move or rename, so old values are still used	Compare the From address on a test message with the site's mail settings and the module configuration	Update the default sender in both places, and set a reply-to address if replies must go to a monitored mailbox
Duplicate messages	Queue items are retried after a timeout even though the relay accepted the first attempt, or the same action runs twice	Check whether the recipient received two messages with the same subject and timestamp, and review queue retry settings and worker timeouts	Increase worker timeout beyond typical send time, keep retries bounded, and review the code that triggers the mail
Delayed messages	Cron interval is too long, the queue worker is starved by other jobs, or the relay is throttling the account	Measure the time between queueing and relay acceptance, and check the relay's rate limits and rejection messages	Shorten the cron interval or run a dedicated queue worker, and ask the relay what sending limits apply to your account
Mail works in test but fails in production	Environment-specific credentials or a blocked outbound port on the production network	Compare SMTP settings between environments and test outbound connections from the production web nodes	Store relay settings per environment and request firewall rules for the relay's ports from your network team

How to test email delivery before go-live

Testing email delivery before go-live means proving that every Drupal mail path reaches a real inbox through the relay you chose, with authentication results you can read and defend. Start by listing each path that sends mail: new account registration, password reset, workflow notifications for content moderation, and webform confirmations. Trigger each one from a test account on a staging copy that uses the same SMTP or Mailer Plus transport configuration as production, and send to mailboxes at several inbox providers that your users actually use. Record the sender address, subject, and whether the message arrived in the inbox, spam, or not at all.

For each received message, open the full header rather than relying on a summary view. Look for the Authentication-Results header added by the receiving server and confirm that SPF, DKIM and DMARC each report a pass for the sending domain. Check that the From domain aligns with the domain used in the DKIM signature and the SPF return path, since DMARC alignment fails even when SPF or DKIM individually pass. Confirm the DMARC policy the domain publishes matches what your security team expects. Results depend on the sending domain, the DNS records, and the provider, so repeat this check in your own environment rather than assuming a vendor's guidance applies unchanged.

Then test failure behavior on purpose. Send to an address that does not exist and confirm how bounces are logged, whether the site surfaces an error to the user, and whether anyone is alerted. Point the transport at an unreachable host or a wrong credential in staging and confirm that the failure is recorded and does not block page saves. Finally, queue a large batch of messages while the relay is slow and confirm how backlog drains, whether the Drupal queue or cron processes the messages in order, and how long a notification can wait before a user notices. Agree the acceptable delay and the owner of bounce review before the first production run.

Questions teams ask before configuring Drupal email

What drives the cost and effort of configuring Drupal email?

The main drivers are the module choice (SMTP Authentication Support or Mailer Plus), the number of mail paths, the scope of HTML templates, the level of DNS access you can grant, and how deep the testing goes. A single outbound path with one provider is a small job. Separate paths for password resets, form notifications, bulk messages and transactional alerts each need routing, testing and sometimes their own sending identity. Ask any quote to itemize these components, and to state which items are one-time (configuration, DNS records, templates) and which recur (provider fees, monitoring, template changes).

How long does Drupal email configuration take?

Duration depends on how many mail paths exist, how quickly your team can create a provider account and approve DNS changes, and how many rounds of testing your deliverability targets require. The DNS and provider steps often set the pace because they depend on people outside the project. Ask for a written schedule that separates the technical build from waiting on approvals and DNS propagation, and confirm which items you own. No fixed duration applies to every site.

Can an internal team configure Drupal email without a partner?

Yes, a team with Drupal administration experience and someone who can manage DNS can usually do it alone, especially for a single outbound path. The work needs an engineer who can install and configure a contributed module through Composer, a Drupal developer who understands the mail system and its hooks, and someone comfortable reading SPF, DKIM and DMARC records. Where mail carries password resets or regulated notices, a second reviewer who checks headers and authentication results reduces the risk of a silent failure.

What does the client need to provide for this work?

Plan to supply a sending account with a transactional email provider or your own SMTP relay, credentials stored in your secrets system, DNS access or a DNS change process for the sending domain, approval from the people who own the domain and mail policy, and test mailboxes across the providers your users rely on. Also provide a list of every mail path your site uses, such as registration, notifications and forms. Without that inventory, the testing scope is incomplete.

Does my Drupal version affect which email module to choose?

Yes. Mailer Plus (DSM+) 2.0.2 supports Drupal ^10.3 or ^11, so it is not an option on older branches. Drupal 10 reaches end of life on December 9, 2026, and Drupal 12 is scheduled for the week of December 7, 2026, so sites planning a move should confirm module compatibility before choosing. Drupal 7 security support ended on January 5, 2025, and Drupal 7 sites cannot be updated in place, so they need a migration plan before the mail design is finalized. Check the compatibility statement on each project page before committing.

How is ongoing monitoring and provider change handled?

Monitoring covers bounce and failure rates in your provider console, authentication results on sent messages, DNS record drift, and Drupal's own logs for failed sends. Provider changes require updating credentials or endpoints, retesting SPF and DKIM alignment, and checking that templates still render. Agree in writing who watches these signals, how often, and who handles a provider switch. Ongoing support and continuous checks can be arranged as a retainer, and the scope of that retainer should be set in the written agreement.

Does Drupal email configuration have licensing costs?

Drupal and contributed modules on Drupal.org are licensed under GPL-2.0-or-later, and there is no paid edition of Drupal itself, so the module cost is zero. Your recurring costs come from the email provider or relay you choose, its volume pricing, and the labor to operate it. Confirm the terms of any provider directly with that provider, since those terms are outside Drupal's licensing.

How DeployOpen scopes Drupal email delivery

DeployOpen plans, implements, hardens and documents Drupal email delivery inside your own infrastructure, whether that is your cloud account, a data center or an air-gapped network. The work covers choosing between the SMTP Authentication Support module and Mailer Plus, configuring the relay or transactional email service, building HTML templates, setting up SPF and DKIM for your sending domains, and testing delivery end to end. Most engagements are fixed-scope, so the list of sites, mail types, relay accounts and DNS zones in scope is agreed in writing before any configuration begins, along with the deliverables and timelines. Ongoing monitoring of bounces, relay changes and Drupal updates that touch mail can be covered by a retainer.

The written scope is also where you settle what DeployOpen does not do. DeployOpen does not issue audit reports, attestations or certifications. If your mail program must support a compliance assessment, DeployOpen can prepare the configuration, records and test evidence an independent auditor or certification body will ask for, but the assessment itself stays with that auditor. Confirm early which evidence your assessor expects, such as DNS records, relay logs and test results, so it is captured during the build rather than reconstructed later.

A quote follows from that written scope, so the more precisely you describe your inputs, the more precise the quote. Before you ask for one, confirm who owns the sending domains and DNS, which relay or transactional provider account you will use and who holds its credentials, how many Drupal sites send mail, and which message types need to be tested. Your own team should also confirm your Drupal version and PHP version against the current requirements, because the Mailer Plus release you can use depends on them.

Drupal email delivery with SMTP and Symfony Mailer