Joomla Mail changes: Joomla 3 → 4, 5 and 6

5 issues in this guide

Mail is a container service now, not a JFactory side door. This guide groups 5 entries: JFactory::getMailer(), JMail, JMail::sendAdminMail(), JMailHelper, JMail::send() returned false. getMailer() is deprecated since Joomla 4.4; resolve the mailer from the DI container and build messages explicitly instead of JMail::sendAdminMail(). Wrap send() in try/catch for MailDisabledException and RuntimeException — boolean false returns are not the modern failure signal. Class aliases for JMail / JMailHelper still exist through Joomla 5 with the BC plugin and disappear on native Joomla 6. Hop mix: 2 at Joomla 3 → 4; 1 at Joomla 4 → 5; 2 at Joomla 5 → 6. After you rename classes, send a test message on staging with mail disabled and with a broken SMTP host so you know your catch paths work. Each entry below has the before/after call shape from the catalog to paste into helpers and notification plugins. Catalog replacements in this guide include JFactory::getMailer() → Mailer from the container; JMail → Joomla\CMS\Mail\Mail; JMail::sendAdminMail() → Build a Mailer message yourself; JMailHelper → Joomla\CMS\Mail\MailHelper. Open each h2 anchor for the full before/after, fix list, and error strings shipped in the reference data.

JFACTORY-GETMAILER-001

JFactory::getMailer()

Factory::getMailer()

getMailer() is deprecated since 4.4. Mail is a container service. Exceptions now bubble — wrap send() in try/catch.

JFactory::getMailer() → Mailer from the container

Dies at Joomla 4 → 5
Dies at Joomla 4 → 5J3: Works nativelyJ4: Deprecated — do not shipJ6: Deprecated — do not shipBC plugin: not applicablePatch possible — review itJoomla API

What you will see

  • Factory::getMailer is deprecated

Symptoms people search

mail send fatal instead of silent fail

Replace this code

Swap JFactory::getMailer() for Mailer from the container.

Joomla 3

Remove or stop calling this

$mailer = JFactory::getMailer();

Joomla 4 / 6

Use this instead

$mailer = Factory::getContainer()->get(\Joomla\CMS\Mail\MailerFactoryInterface::class)->createMailer();

How to fix it

  1. 1Resolve the mailer from the container.
  2. 2Catch MailDisabledException.

Also known as

getMailer

Scan a ZIP for thisAsk Infyways to fix it

JMAIL-CLASS-001

JMail

JMail class name

JMail is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JMail" not found.

JMail → Joomla\CMS\Mail\Mail

Dies at Joomla 5 → 6
Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

  • Class "JMail" not found
  • Class 'JMail' not found
  • Failed to open stream: JMail

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JMail for Joomla\CMS\Mail\Mail.

Joomla 3

Remove or stop calling this

JMail::getInstance();
// or new JMail()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Mail\Mail;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

  1. 1Add a use statement for Joomla\CMS\Mail\Mail.
  2. 2Replace every JMail with the short class name from that use line.
  3. 3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JMail · Joomla\CMS\Mail\Mail · class alias · J prefix

Scan a ZIP for thisAsk Infyways to fix it

JMAIL-SENDADMINMAIL-001

JMail::sendAdminMail()

JMail::sendAdminMail()

sendAdminMail() was removed in Joomla 4.

JMail::sendAdminMail() → Build a Mailer message yourself

Dies at Joomla 3 → 4
Dies at Joomla 3 → 4J3: Works nativelyJ4: Removed — fatalJ6: Removed — fatalBC plugin: no — already dead on J4Patch possible — review itJoomla API

What you will see

  • Call to undefined method ...::sendAdminMail

Symptoms people search

admin notification mail fatal

Replace this code

Swap JMail::sendAdminMail() for Build a Mailer message yourself.

Joomla 3

Remove or stop calling this

JFactory::getMailer()->sendAdminMail($from, $fromName, $subject, $body);

Joomla 4 / 6

Use this instead

$mailer = Factory::getApplication()->getMailer();
$mailer->addRecipient($adminEmail);
$mailer->setSubject($subject);
$mailer->setBody($body);
$mailer->Send();

How to fix it

  1. 1Send to the mailfrom/fromname config addresses explicitly.

Also known as

sendAdminMail

Scan a ZIP for thisAsk Infyways to fix it

JMAILHELPER-CLASS-001

JMailHelper

JMailHelper class name

JMailHelper is a Joomla 3 global class. Joomla 4 still has an alias. Joomla 5 needs the Behaviour – Backward Compatibility plugin. Native Joomla 6 does not load that alias — you get Class "JMailHelper" not found.

JMailHelper → Joomla\CMS\Mail\MailHelper

Dies at Joomla 5 → 6
Dies at Joomla 5 → 6J3: Works nativelyJ4: Alias (old name still resolves)J6: Removed — fatalBC plugin: covers the class nameMechanical renameJoomla API

What you will see

  • Class "JMailHelper" not found
  • Class 'JMailHelper' not found
  • Failed to open stream: JMailHelper

Symptoms people search

white screen after disabling compatibility plugin · class not found on Joomla 6 · works on Joomla 5 until I turn off backward compatibility

Replace this code

Swap JMailHelper for Joomla\CMS\Mail\MailHelper.

Joomla 3

Remove or stop calling this

JMailHelper::getInstance();
// or new JMailHelper()

Joomla 4 / 6

Use this instead

use Joomla\CMS\Mail\MailHelper;

// Call the namespaced class. Do not keep the J prefix.

How to fix it

  1. 1Add a use statement for Joomla\CMS\Mail\MailHelper.
  2. 2Replace every JMailHelper with the short class name from that use line.
  3. 3Disable Behaviour – Backward Compatibility on a Joomla 5 staging site. If it fatals, this class is still in the code.

Also known as

JMailHelper · Joomla\CMS\Mail\MailHelper · class alias · J prefix

Scan a ZIP for thisAsk Infyways to fix it

MAIL-DISABLED-001

JMail::send() returned false

MailDisabledException bubbles

Joomla 3 swallowed mail failure as false. Joomla 4 throws. Uncaught exceptions become a 500 on “send email”.

JMail::send() returned false → try/catch MailDisabledException and RuntimeException

Dies at Joomla 3 → 4
Dies at Joomla 3 → 4J3: Works nativelyJ4: Changed behaviourJ6: Changed behaviourBC plugin: not applicablePatch possible — review itJoomla API

What you will see

  • Class "Joomla\CMS\Mail\Exception\MailDisabledException"
  • Uncaught PHPMailer

Symptoms people search

mail send 500 · MailDisabledException · ErrorInfo

Replace this code

Swap JMail::send() returned false for try/catch MailDisabledException and RuntimeException.

Joomla 3

Remove or stop calling this

if (!$mailer->Send()) { echo $mailer->ErrorInfo; }

Joomla 4 / 6

Use this instead

try {
    $mailer->send();
} catch (\Joomla\CMS\Mail\Exception\MailDisabledException $e) {
    // Mail off in Global Config
} catch (\PHPMailer\PHPMailer\Exception $e) {
    $app->enqueueMessage($e->getMessage(), 'error');
}

How to fix it

  1. 1Wrap send() in try/catch.
  2. 2Do not read ErrorInfo as the only failure path.

Also known as

MailDisabledException · ErrorInfo · PHPMailer

Scan a ZIP for thisAsk Infyways to fix it

Start a project

Have something
to build?

Tell us what you are building. You will hear back from an engineer within one business day.

hello@infyways.com · Remote, working across time zones

Tell us about your project

Fill out the quick form and we'll reach out.