Drupal SMTP Module + Inbox Placement: Complete Guide

Drupal's smtp contrib module is the standard fix for the PHP-mail-goes-to-spam problem. It is small, well maintained, and works with any SMTP-speaking provider. But installing the module is only the first of three steps. Authentication, DNS and content each have to be right for mail to land in the inbox consistently. This guide walks through all three and ends with a placement test.

What "working" looks like

A newly registered user on your Drupal site receives the confirmation email in their Gmail primary inbox within seconds. Headers show spf=pass, dkim=pass, dmarc=pass. The email is not in Promotions, not in Spam. You have verified this across at least ten seed mailboxes.

Install and enable

From the project root:

composer require drupal/smtp
drush en smtp -y
drush cr

Then head to Configuration → System → SMTP Authentication Support (URL path /admin/config/system/smtp).

Configure

Install options

Turn this module on or off: On. When Off, Drupal falls back to the previous mail_system.
Allow to send e-mails formatted as HTML: On only if your templates render HTML. Most Drupal templates use plain text plus optional HTML — leave on unless you know otherwise.

SMTP server settings

SMTP server: provider host.
SMTP backup server: optional. Only useful if you have a failover setup.
SMTP port: 587 for TLS, 465 for SSL. Prefer 587.
Use encrypted protocol: TLS.

SMTP authentication

Username and Password: from the provider.

Common provider values:

Postmark
  Host:     smtp.postmarkapp.com
  Port:     587 (TLS)
  User:     <server API token>
  Pass:     <server API token>

SendGrid
  Host:     smtp.sendgrid.net
  Port:     587 (TLS)
  User:     apikey
  Pass:     <SendGrid API key>

Mailgun
  Host:     smtp.mailgun.org      (or smtp.eu.mailgun.org for EU region)
  Port:     587 (TLS)
  User:     postmaster@mg.yoursite.org
  Pass:     <Mailgun SMTP password>

Amazon SES
  Host:     email-smtp.<region>.amazonaws.com
  Port:     587 (TLS)
  User:     <SES SMTP user>
  Pass:     <SES SMTP password>

E-mail options

E-mail from address: a mailbox on the authenticated domain, e.g. noreply@yoursite.org. Do not set this to a Gmail / Outlook address — DMARC at the recipient will reject it.
E-mail from name: public brand name.

Save. Then use Send test e-mail at the bottom of the form and check your inbox.

From-address alignment is the single most common bug

DKIM signs using the provider's key for your domain. That only works if the From address is on your domain and the DKIM record for your domain is published. If the From address is on a different domain than what the provider signs, DKIM does not align and DMARC fails. Set From to a mailbox on yoursite.org and publish DKIM there, not elsewhere.

TLS, ports, firewall

Port 587 with STARTTLS is the modern default. Some legacy hosts only allow port 465 (implicit SSL). Both work, but:

Port 587 + TLS uses STARTTLS (plaintext connection upgraded to TLS).
Port 465 + SSL uses implicit TLS from the first byte.

If the SMTP test hangs: your host blocks outbound SMTP. Container hosts and some PaaS setups do this. Switch to an API-based module (Mailgun, SendGrid) which sends over HTTPS on port 443 — always allowed.

DNS alignment

With the provider receiving mail from Drupal, you still need DNS for authentication. Example for Mailgun:

; SPF
yoursite.org.           IN  TXT  "v=spf1 include:mailgun.org ~all"

; DKIM (Mailgun gives you the key value)
s1._domainkey.yoursite.org.  IN  TXT  "k=rsa; p=MIGfMA0GCSq...AQAB"

; DMARC
_dmarc.yoursite.org.    IN  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@yoursite.org; adkim=r; aspf=r"

Resend the Drupal test mail to a Gmail address. Open "Show original". Verify all three: spf=pass, dkim=pass, dmarc=pass. If any one fails, fix it before moving on.

Drupal integration in beta

A native Drupal extension is in private beta — schedule placement tests from admin and alert on drops.

→ Join the beta waitlist

Run a placement test

Authentication passes the cryptographic gate. It does not guarantee primary-inbox placement. Gmail may still send your mail to Promotions based on content. To see real placement, run a seed test.

Open check.live-direct-marketing.online and generate 20+ seed addresses: Gmail, Outlook, Yahoo, Mail.ru, Yandex, GMX, Web.de, ProtonMail.
Register a new Drupal user with the first seed. Watch the confirmation email land across providers. The panel shows Inbox / Promotions / Spam per address.
Trigger a password reset for an existing seed account. Re-test. Password resets scan differently than registrations (single link, no marketing content).
Submit a Webform or Contact form as a seed. Confirm the notification to the admin mailbox.

When to pick a different provider

Provider choice matters more than SMTP-module configuration. A rough heuristic:

Postmark — best default for low-volume transactional (under 50k/month). Separates transactional and bulk streams, strong shared IPs.
Amazon SES — cheapest at scale if you are already on AWS. Requires moving out of sandbox mode and a short reputation warm-up.
SendGrid — robust, if you are comfortable with their IP-pool tiers.
Mailgun — strong European region option (EU data residency).
Brevo (ex-Sendinblue) — free tier of 300/day covers small sites at zero cost.

If the SMTP module test works but your placement is bad, switch provider first before deeper debugging. A clean provider on an aligned domain is 95% of the battle.

FAQ

The SMTP module supports OAuth2 — should I use it?

OAuth2 in the smtp module is mainly used for Gmail (via Google Workspace) and Microsoft 365. If you are sending transactional mail through those providers, yes — it avoids long-lived passwords. For Postmark / SES / Mailgun, SMTP with API token is simpler.

Can I keep the SMTP credentials out of config files?

Yes. Drupal 9+ supports overriding config from settings.php, which in turn can pull from environment variables. Put SMTP password in an environment variable and reference it in settings.php via $config['smtp.settings']['smtp_password']. Do not commit the password to version control.

The module says "mail sent" but nothing arrives. What next?

Check the provider's dashboard first — Postmark, SendGrid and Mailgun all show delivery events. If the provider shows "delivered", the issue is at the recipient side (spam folder). If the provider shows "rejected" or "bounced", the issue is upstream (bad From address, blocklisted recipient, content).

Does the SMTP module queue mail or send synchronously?

Synchronously by default. That means a slow SMTP provider blocks the request thread. For high-traffic sites, combine the SMTP module with the core Queue API or the Mail Queue contrib module to send asynchronously. Transactional mail usually does not need async — it is infrequent and low-latency.

Drupal SMTP module: config + inbox placement end to end