Email troubleshooting in Joomla
Sooner or later a Joomla site owner sends the same message: "Someone filled in my contact form and I never got the email." Most of the time the form worked perfectly. The email left Joomla and then failed somewhere you cannot see, unless you know where to look. The good news is that email leaves a detailed trail, and reading it turns guesswork into a quick diagnosis.
This article is the diagnostic companion to the Focus On articles on Email and Joomla and Email Deliverability. Those explain how to set mail up correctly; this one explains how to find out why a message failed. It covers a layered testing method, how to read email headers, the meaning of common SMTP error codes, the tools that tell you the truth, and the Joomla-specific traps that catch people out.
When email fails, stop guessing and read the trail it left.
The goal is to give owners, administrators, and developers a repeatable way to locate an email problem instead of changing settings at random and hoping.
1. Test in Layers, Not at Random
The biggest time-waster in email troubleshooting is changing many things at once. Email passes through several independent layers, so test them in order and stop at the first one that fails. That single failing layer is your problem.
1.1 The Four Layers
| Layer | How to test it | If it fails |
|---|---|---|
| 1. Transport | Send Test Mail in Global Configuration | Fix SMTP settings first; nothing else matters yet. |
| 2. System mail | Request a password reset for a test user | Joomla's mailer or templates, not your form. |
| 3. Extension mail | Submit the real form (contact, RSForm Pro) | The extension, or which mailer it uses. |
| 4. Deliverability | Send to Gmail and Outlook, read the headers | SPF, DKIM, DMARC, or reputation. |
1.2 Why Order Matters
If transport (layer 1) fails, every layer above it fails too, so there is no point editing a form or a DNS record yet. If the test mail arrives but your contact form does not, you have just proved the problem is in the form or the extension, not in SMTP. Each passing layer rules out a whole category of cause. This is the fastest path to the answer.
Back to top2. The Joomla Send Test Mail Button
Your first and most useful tool ships with Joomla. It tests transport on its own, separate from any form or template.
2.1 Where It Is
System → Global Configuration → Server tab → Mail Settings
└─ Send Test Mail (button at the top of the screen)Save your settings first, then click it. Joomla sends a small message to the From address using your exact Mailer and SMTP settings.
2.2 Reading the Result
- It arrives: transport works. Any remaining problem is in a template, a form, or deliverability, so move up the layers.
- It errors on screen: Joomla usually shows the real reason, such as authentication failed or connection refused. That message points straight at the cause (see section 4).
- It says sent but never arrives: transport handed off but delivery failed later. Suspect deliverability and check the headers of a message that does arrive elsewhere.
2.3 Keep a Good Sample
When the test mail does arrive, keep it. A known-good message is the perfect thing to compare against a failing one later, header by header.
Back to top3. Reading Email Headers
Every email carries hidden headers: technical metadata that records the whole journey. Learning to read them is the single most valuable email troubleshooting skill, because the headers usually contain the answer outright.
3.1 How to See the Headers
| Client | Where to look |
|---|---|
| Gmail | Open the message, the three-dot menu, then "Show original". |
| Outlook desktop | Open the message, File, Properties, "Internet headers". |
| Outlook on the web | The three-dot menu, then "View message details". |
| Thunderbird | View, "Message Source", or press Ctrl+U. |
| Apple Mail | View, Message, "All Headers" or "Raw Source". |
3.2 The Header That Answers Most Questions
Look first at Authentication-Results. It states the verdict on the three deliverability checks in plain words:
Authentication-Results: mx.recipient.com;
spf=pass (sender IP is authorised)
dkim=pass (signature valid; d=yourdomain.com)
dmarc=pass (policy applied)If one reads fail, you know precisely where to start. An spf=fail points at your SPF record or sending server; a dkim=fail at your DKIM key; a dmarc=fail usually at alignment. The Email Deliverability article explains how to fix each one.
3.3 The Received Chain
The Received headers are a stack added by every server the message touched. Read them from the bottom up: the lowest entry is where the message began, the top is where it arrived.
Received: by mx.recipient.com ... (top: final delivery)
Received: from relay.provider.com ... (middle: your SMTP provider)
Received: from yoursite ... (bottom: the journey started here)Large time gaps between entries point to a delay such as greylisting or a queue, not a hard failure.
3.4 Other Useful Fields
| Header | What it tells you |
|---|---|
From |
The address shown to the recipient. Not proof of authenticity on its own. |
Return-Path |
The envelope sender, where bounce messages go. |
Message-ID |
A unique ID for the message; use it to find the same mail in server logs. |
DKIM-Signature |
The signature itself; d= is the signing domain, s= the selector. |
X-Mailer |
What sent the mail (often PHPMailer for Joomla), a clue to which system was used. |
4. Common SMTP Error Codes
When transport fails, the SMTP server replies with a numeric code. Joomla often shows it in the Send Test Mail error or your server logs. The first digit tells you the category: 2xx is success, 4xx is a temporary problem worth retrying, 5xx is a permanent rejection.
| Code | Meaning | Usual cause in Joomla |
|---|---|---|
| 250 | Action completed | Success; the server accepted the message. |
| 421 | Service unavailable | Server busy or throttling; retry later. |
| 450 / 451 | Temporary failure | Often greylisting; it usually succeeds on retry. |
| 530 | Authentication required | SMTP Authentication is off, or no login was sent. |
| 535 | Authentication failed | Wrong username or password; often a missing App Password. |
| 550 | Mailbox unavailable / relay denied | Bad recipient, or the server refuses to relay for you. |
| 554 | Transaction failed | Often a reputation or blocklist rejection. |
A 535 on Google or Microsoft 365 almost always means you used a normal account password where an App Password or enabled SMTP AUTH is required, as covered in the Email and Joomla article.
5. Diagnostic Tools
A handful of tools tell you the truth about your setup so you do not have to guess.
5.1 Online Services
| Tool | Use it to |
|---|---|
| Mail Tester | Send a message and get a spam score plus SPF, DKIM, and DMARC results. |
| MXToolbox | Check DNS, MX, SMTP, and whether your IP or domain is on a blocklist. |
| Google Postmaster Tools | See your reputation and delivery with Gmail over time. |
5.2 Command-Line Checks
dig example.com TXT see the SPF and other TXT records
dig _dmarc.example.com TXT see the DMARC policy
dig example.com MX see which server receives the domain's mail
nslookup -type=TXT example.com the same on Windows5.3 Catching Mail on a Test Site
On local or staging sites, point Joomla's SMTP host at a mail-catcher such as MailHog or Mailpit. It accepts every message and shows it in a web interface, so you can inspect exactly what Joomla produced without sending anything to a real person. This is the safest way to test forms and templates.
5.4 Turning On Joomla Debugging
During development, enable Debug mode in Global Configuration and check the error log. For deeper SMTP detail, a developer can raise PHPMailer's debug level in a small test script to watch the full SMTP conversation, including the server's exact replies.
Back to top6. Which Mailer Actually Sent It?
This question solves a surprising share of "some email works, some does not" cases. Not every extension sends mail the same way, so before you debug, find out which system handled the message.
6.1 The Two Kinds of Extension
- Uses Joomla's mailer: core Contact, user registration, password reset, and RSForm Pro all send through Joomla's central settings. Fix these in Global Configuration.
- Has its own mail config: AcyMailing and some CRM or marketing tools keep separate SMTP settings. Fix these in the extension's own screen.
6.2 A Quick Decision Table
| Symptom | Where to look |
|---|---|
| Password reset and contact form both fail | Joomla Global Configuration (shared mailer) |
| RSForm Pro form fails, system mail works | The form's notification setup; mailer is still Joomla's |
| AcyMailing newsletter fails, everything else works | AcyMailing's own mail configuration |
| Every kind of mail fails at once | Transport or DNS; a shared cause like a blocked port |
The X-Mailer header from section 3.4 can also reveal which system produced a given message, which settles the question quickly.
7. Delays and Spam-Folder Problems
Not every problem is a hard failure. Two milder cases need a different approach.
7.1 The Message Is Slow, Not Lost
If mail arrives but late, check the timestamps in the Received chain. A gap of a few minutes on the first message to a new recipient is usually greylisting: the receiver asked your server to retry, and it did. This is normal and self-correcting. Larger or growing gaps suggest a congested queue or a struggling SMTP server.
7.2 It Arrives, but in Spam
If authentication passes yet messages still land in spam, the problem is reputation or content, not setup. Check, in order:
- Blocklists: is your sending IP or domain listed? Check with MXToolbox.
- Reverse DNS: does the sending IP have a matching PTR record? A good provider ensures this.
- Content: avoid all-caps subjects, spammy phrases, and link-only bodies.
- A plain-text part: send multipart so strict filters see clean text too.
The Email Deliverability article covers reputation, reverse DNS, and blocklists in full.
Back to top8. Under the Hood: Where Joomla Records Email
For administrators and developers, a few Joomla internals help when transport itself is not the issue.
8.1 Relevant Database Tables
| Table | Why it matters to email |
|---|---|
#__users |
The email column is the destination; sendEmail controls admin notifications; block can stop activation mail mattering. |
#__user_keys |
Holds the temporary tokens emailed for password reset and activation. An expired or missing token explains a dead reset link. |
#__mail_templates |
The editable text of each system email. A deleted tag here breaks an otherwise well-delivered message. |
8.2 Content Versus Delivery
Keep the split clear. If mail does not arrive, the problem is delivery: transport or DNS. If mail arrives but says the wrong thing, or a reset link is broken, the problem is content, which lives in the Mail Templates component. The Focus On article on Joomla Mail Templates covers that side. Knowing which screen owns which problem saves hours.
8.3 Logging Failures in Custom Code
A developer whose extension sends mail should always check the return value of the send call and log failures with the recipient, subject, and SMTP error. Silent failures are the hardest to diagnose later, and a one-line log entry turns a mystery into a quick fix.
Back to top9. Common Mistakes and Pitfalls
9.1 Editing the Form to Fix Non-Delivery
Symptom: No mail arrives, so you keep rebuilding the contact form.
Fix: Test transport with Send Test Mail first. If that fails, the form is irrelevant; fix SMTP.
9.2 Ignoring the On-Screen Error
Symptom: The test mail fails and you start changing settings blindly.
Fix: Read the error. "Authentication failed" and "connection refused" each point at a specific cause; do not guess past them.
9.3 Debugging the Wrong Mailer
Symptom: You change Global Configuration for hours, but the failing newsletter still fails.
Fix: AcyMailing uses its own mail config. Confirm which system sent the message before you touch any setting.
9.4 Mistaking a Delay for a Failure
Symptom: A message is missing, so you resend it many times; later all the copies arrive.
Fix: It was greylisted. Wait a few minutes for the retry instead of resending.
9.5 Testing Once and Trusting It Forever
Symptom: Mail worked at launch but silently broke months later.
Fix: App passwords expire, providers change policies, and IPs get blocklisted. Re-test after provider or DNS changes, and watch DMARC reports.
Back to top10. Best Practices
If you remember only a few things from this article, remember these:
- Test in layers from transport upward, and stop at the first failure.
- Start with Send Test Mail; it isolates transport from forms and templates.
- Learn to read
Authentication-Resultsand theReceivedchain; the answer is usually there. - Match an SMTP error code to its cause instead of guessing (535 means bad login, 530 means no auth).
- Always find out which mailer sent a message before changing settings.
- Keep a known-good message to compare a failing one against.
- Use Mail Tester and MXToolbox to check authentication and blocklists.
- Catch mail with MailHog or Mailpit on test sites so you never send to real people.
- Re-test after provider and DNS changes; email setups break quietly over time.
11. Quick Reference
LAYERED TEST
1 Transport Send Test Mail (Global Configuration)
2 System mail request a password reset
3 Extension mail submit the real form (contact / RSForm Pro)
4 Deliverability send to Gmail + Outlook, read the headers
KEY HEADERS
Authentication-Results spf= / dkim= / dmarc= (pass or fail)
Received read bottom to top = the route
Return-Path where bounces go
Message-ID match the mail in server logs
X-Mailer which system sent it
SMTP CODES
250 ok 421/450/451 temporary (retry)
530 auth required 535 auth failed (bad login / no App Password)
550 mailbox/relay denied 554 reputation / blocklist
TOOLS
dig example.com TXT | Mail Tester | MXToolbox | Postmaster Tools
MailHog / Mailpit catch mail on test sites
Joomla Debug mode server error log
WHICH MAILER
Joomla's core, registration, password reset, RSForm Pro
Its own AcyMailing, some CRM / marketing tools12. Summary
Email troubleshooting feels like guesswork only until you follow the trail every message leaves:
- Test in layers and stop at the first failure; each passing layer rules out a whole cause.
- Send Test Mail isolates transport, your fastest first check.
- Headers, especially
Authentication-Resultsand theReceivedchain, name the problem outright. - SMTP error codes map to specific causes; 535 is a bad login, 550 a refused recipient.
- Which mailer sent it decides which screen to open: Joomla's settings or the extension's own.
- Delays and spam are different from failures and need reputation and content fixes.
With a layered test, a careful read of the headers, and the right tool for each layer, almost any Joomla email problem becomes a short, methodical hunt rather than an afternoon of guesswork. If your site's mail still misbehaves after you have worked through these steps, the trouble is usually subtle, in DNS alignment, reputation, or an extension's hidden mail config, and that is exactly the kind of problem a focused second look can resolve quickly.
Back to top
Frequently Asked Questions
Joomla may stop sending emails due to incorrect SMTP settings, an unreachable mail server, authentication failures, firewall restrictions, or hosting limitations. Checking the Joomla Mail settings, SMTP credentials, and server logs usually reveals the cause.
Go to System → Global Configuration → Server → Mail Settings. Select SMTP, enter your SMTP host, port, username, password, and encryption method (SSL/TLS or STARTTLS). Save the settings and send a test email to verify the configuration.
Use Joomla's built-in mail functionality or a contact form to send a test email. If it fails, review the error message, enable Joomla Debug Mode, and check your web server or PHP error logs for additional details.
Emails often end up in spam because SPF, DKIM, or DMARC records are missing or incorrect, the sending domain has a poor reputation, or the email content triggers spam filters. Proper DNS authentication significantly improves deliverability.
SMTP is the recommended mailer for most Joomla websites because it provides secure authentication and better delivery rates than PHP Mail. Services such as Gmail SMTP, Microsoft 365, Amazon SES, Mailgun, and SendGrid are popular choices.
When choosing an SMTP provider, also consider privacy and GDPR compliance. If you handle personal data, using a European email service or a provider with appropriate GDPR safeguards may be preferable.
Verify the SMTP hostname, port, encryption method, username, and password. Ensure the SMTP server allows external connections, and if using Gmail or Microsoft 365, use an app password or OAuth where required. Server logs often provide the exact authentication error.
