Configure Joomla 3.X mail to work with SMTP and GSuite

Configure Joomla 3.X Mail with SMTP and GSuite (Google Apps)

Configure Joomla 3.X mail to work with SMTP and GSuite

This post includes a step-by-step guide on how to properly configure Mail Settings in Joomla 3.X global configuration using SMTP settings and GSuite as your email provider. The visual guide includes lots of useful pictures and troubleshooting guidance.

This visual guide will walk you through the steps of setting up SMTP mail in Joomla while using a GSuite email address under your custom domain. If you don’t need the full guide, then see the TL;DR version below. Note that this solution works as of the publication date of the post (April 1st, 2017) - but isn't an April Fools' joke.

Otherwise, you can skip to the full guide.

TL;DR Version - Send global mail using SMTP and GSuite in Joomla 3.X

The steps listed below explain how to get SMTP mail working on Joomla 3.X while using GSuite as your custom domain email provider.

TL;DR Version - Joomla 3.X SMTP mail with GSuite setup

Below is a condensed version of the entire guide on how to set up SMTP mail in the Joomla Global Configuration panel.

Step 1: Log into your Google Admin panel with administrative privileges. Go to Security > Basic settings and check the box that says “Allow users to turn on 2-step verification.”
Step 2: Log into your individual Google account dashboard and head over to Sign-in & security > Signing in to Google > 2-Step Verification. Follow the steps to turn on two-step authentication.
Step 3: In your Google account, go to the App Passwords section and add a new app password with the following values:
  • Select app: Mail
  • Select device: Other (custom name)
Enter anything (like “My Joomla website mailer”) in the custom name and click Generate. You will see a 16-digit password. Save this password.
Step 4: Go to the administrative panel of your Joomla instance and find System > Global Configuration > Server > Mail Settings. Scroll down to Mail Settings and it will be on the bottom-right.

Enter the following Mail Settings values:
  • Send Mail: Yes
  • Enable Mass Mail: Doesn’t matter
  • From Email: Enter the email address that you created the app password for in the previous step
  • From Name: Enter the name that you want email recipients to see
  • Mailer: SMTP
  • SMTP Host: smtp.gmail.com
  • SMTP Port: 587
  • SMTP Security: STARTTLS
  • SMTP Authentication: Yes
  • SMTP Username: Enter the email address you created the app password for in step 3.
  • SMTP Password: Enter the app password you created in step 3.
Click Save on the top-left and then test by clicking Send Test Mail below the Mail Settings.
All done! That’s it. If you check the email address you set up you should have received a test email, showing you that it works.

If it didn't work, head down to the troubleshooting section or try the entire visual guide.

Background information on Joomla’s mailer

I recently spent some time setting up a new instance of Joomla 3.X and was playing around with the different mailing options under System > Global Configuration > Server (tab) > Mail Settings.

By default, the Joomla CMS sends mail for various reasons. Examples include user registration, mass mailing, and password reset tokens. PHP Mail is the default setting I used and I simply added my personal Gmail address to get it to work. The default mail settings are shown below using PHP Mail:

Default Joomla 3.X Mail Settings - By default, Joomla 3.X uses the PHP Mail option to send global mail within the global configuration panel.

It worked out of the box (I received a test email for new user registration), albeit I wasn’t quite happy with a few things:

  • Gmail showed the Gmail padlock warning padlock warning next to the sender address.
  • Gmail showed the dreaded “phishing scam” message

You can see a copy of the email below:

Gmail message for Joomla user registration email - Gmail showed a padlock warning and a phishing warning label on default registration emails sent from Joomla 3.X using the default mail settings (PHP Mail). Source: Gmail screenshot.

Why does Gmail show this warning?

Gmail shows the padlock and other warnings to users when the sender of the email doesn’t have an authenticated domain name. This means that Gmail could not verify that the email actually came from me. It could have been sent by someone else posing as my email address - which is a security issue.

As I wrote about in another blog post about MailChimp domain authentication, email providers are beefing up security when it comes to authenticated senders and domain names. Just putting in whatever email address you want doesn’t fly anymore.

The alternative - Using GSuite (formerly Google Apps for Work) as my email provider

Since I am already a GSuite customer, I wanted to set up my admin(at)bobandedovic.com email address to handle the mail. I own the domain and email address, so I didn’t think it would be an issue.

However, after changing the email address to a GSuite one, I noticed that the mail function ceased to work entirely. That is, mail was not being sent whatsoever from Joomla. I then explored the various mail options within Joomla and saw that none of them worked, even with entering the right credentials.

After spending a few hours researching the issue, I found that you need to go through a few steps within Joomla and the GSuite Admin panel in order to get mail to work using SMTP.

The following guide explains step-by-step how to get this working.

Before you begin

Before you begin going through the steps in this guide, there are a few things that you must have working on your website:

  • Joomla 3.X without core hacks on the mailer files
  • Administrative access to GSuite
  • Basic technical knowledge
  • A GSuite account where email is already working

If you don’t have these items in place then the guide might not work for you. If you are using a different version of Joomla (such as 2.5.X or older) then this guide may work. But use at your own discretion.

Important note: This guide is intended for (and tested to work on) GSuite customers for Google. This guide has not been tested to work on regular old Gmail (youremail[at]gmail.com).

If you do have these items, then you are ready to go!

Step 1: Enable two-step verification in GSuite (Administrative privileges required)

The first thing we have to do is enable two-step authentication in GSuite. This technology adds an additional layer of security to your GSuite account by requiring you to authenticate account access with a code from the Google Authenticator app (or another method).

So, head over to https://admin.google.com and log in using your administrative credentials. From there, click on Security > Basic settings.

GSuite Admin dashboard - Once you log into the Google Admin panel, you will be able to control your GSuite security settings by clicking the Security icon. Source: GSuite Admin screenshot.

GSuite Admin security settings - The security settings page allows you to set organization-wide security rules such as two-factor authentication. Source: GSuite Admin screenshot. Source: GSuite Admin screenshot.

Finally, check the box that says “Allow users to turn on 2-step verification”. Note that you need to have access to an administrator level account to make such changes.

GSuite Admin > Security Settings > Turning on 2-Step Verification - By enabling two-factor authentication, you will allow users in the entire organization to use this advanced security feature. Source: GSuite Admin screenshot.

Make sure that this setting is saved correctly.

Troubleshooting: If you cannot turn this setting on or are otherwise having trouble with it, Google’s help section article is a good resource.

Step 2: Turn on two-step authentication for your individual GSuite account

Now that two-step authentication is turned on for the domain, it’s time to turn it on for the email account that you want to use for the Joomla global mailer.

Head over to https://accounts.google.com and log in with your credentials.

Once you are logged in, go over to Sign-in & security > Signing in to Google > 2-Step Verification.

Google Account security options - Go under Sign-in & security > Signing in to Google > 2-Step Verification to set up two-step verification. Source: Google account screenshot.

Here, you should see a set of screens that walk you through the setup process of two-step verification:

Google 2-Step Verification setup - Follow the three steps to set up two-step verification for your Google account. It’s required to make the Joomla mailer work with a GSuite account. Source: Google account screenshot.

Click the blue GET STARTED button and re-enter your password.

Step 2a: Follow the three steps 2-Step Verification setup process

There are three steps to follow when setting everything up. First, enter the phone number you want to use and click Next.

Google 2-Step Verification setup > Step 1 (phone number) - Enter the phone number you would like to use with your two-step verification. Source: Google account screenshot.

Next, enter the 6-digit code that you received from Google in the code box.

Google 2-Step Verification setup > Step 2 (confirm code) - Google will send a 6-digit code to your phone number as a text message (if you selected that option) or call you with the digits. Source: Google account screenshot.

Once it’s confirmed, click TURN ON to finalize the setup.

Google 2-Step Verification setup > Step 3 (turn on) - Once you enter the correct code, click the TURN ON button to enable two-step verification. Source: Google account screenshot.

Once it’s turned on I strongly recommend that you take the time to create some sort of backup method (at least one). In case your phone gets stolen or is lost you will want to have some means of getting into your account.

Google offers lots of backup options, as shown by the screenshot below:

Google 2-Step Verification > Backup options - In case your phone is lost or stolen, it’s highly recommended to turn on backup options. I recommend the Google prompt option because it’s usually the fastest method to verify the login Source: Google account screenshot.

Here’s a summary of the different alternative second step options and the methods I recommend.

  • Backup codes (recommended): These are one-time use codes that you can use if your phone is unavailable or you otherwise can’t get messages. I recommend setting them up and having at least four codes stored somewhere safely.
  • Google prompt (recommended): If you have the Google app installed on your phone, this method simply asks you if you want to sign in and you can confirm it with a single tap. This method is the most convenient.
  • Authenticator app: This method requires downloading an app from Google that generates a 6-digit code every thirty seconds. You can download it for iOS or Android.
  • Backup phone: Add an additional phone line where the code can be acquired.

Step 3: Create a specific “app password” for email account so that you can use the Joomla mailer

Now we must create a special app password so that the Joomla mailer can be properly authenticated when sending mail from your website.

Head over to Google > Settings > Security > App passwords and select the following options from the drop-down menus:

  • Select app: Mail
  • Select device: Other (custom name)

Google Account > Creating an app password - The app password is created to securely allow third-party applications (such as your Joomla website) access to send email on your behalf. Source: Google account screenshot.

In the custom name box, enter a unique name for the password that you will remember is associated with the Joomla website in question. For this example, I just chose “My Joomla website mailer” as an example, but I recommend including your domain name in here and a reminder that it’s for the mail application.

Google Account > Custom app password name - When you are creating the custom name for your app password, consider giving it a name that you will recognize in the future. Something related to your website name and ‘mailer’ is probably a good idea. Source: Google account screenshot.

Click Generate and a popup will come up with a dedicated app password. Make sure to write this password down as we will use it in another step.

Google Account > Custom app password generated - Once you generate the app password, it will be visible in the yellow box as a 16-digit code. Save this password somewhere safe and treat it as you would any other password. Source: Google account screenshot.

If you closed out of this and didn’t copy it, then just click Revoke on the entry you made and create a new one.

Once it’s created, you should see an entry for it in this section:

Google Account > Managing app passwords - Once you generate the app password and close out of the popup, you will see your new entry in the list. Revoking the password removes it and requires you to create another one following the previous steps provided. Source: Google account screenshot.

Important security note: Treat this app password like you would any other password. Do not share it or upload a picture of it to anyone that you don’t trust (such as an online forum).

Step 4: Set up the Joomla mail credentials in the administrative panel

We’re almost there! Now it’s time to log into your Joomla administrator panel. The URL will look like this by default: yourdomain.com/administrator.

Note that the “/administrator” comes after whatever directory you installed Joomla in. So, if your path to the Joomla homepage is “yourdomain.com/sites/joomla” then the administrator panel will be “yd.com/sites/joomla/administrator”.

Log in and head over to the following page: System > Global Configuration > Server (tab). Scroll down to Mail Settings and it will be on the bottom-right.

Accessing server settings in Joomla 3.X - To access your Mail Settings, log into the administrative panel and go under Joomla Admin panel > System > Global configuration > Server (tab) and scroll down to Mail Settings.

Accessing Mail Settings in Joomla 3.X - To access your Mail Settings, scroll down to Mail Settings from the Server tab in the Global Configuration view.

Hold tight, you are almost there!

Step 4a: Enter new Mail Settings for your GSuite email address

Now that you are under Mail Settings, we are going to apply the following settings/values:

Joomla 3.X Mail Settings for SMTP

Use the following mail setting values for configuring the default Joomla mailer. Don't forget that the SMTP password is not your email password, but the special app password you created in your Google account.

SettingValue
Send Mail Click “Yes” and make sure it’s green
Joomla admin Yes/No button toggle
Disable Mass Mail Doesn’t matter
From Email Enter the email address that you created the app password for in the previous step
From Name Enter the name that you want email recipients to see. I recommend something “webmaster-ish” such as the name of your website
Mailer SMTP
SMTP Host smtp.gmail.com
SMTP Port 587 (required for SSL)
SMTP Security STARTTLS
SMTP Authentication Click “Yes” and make sure it’s green
Joomla admin Yes/No button toggle
SMTP Username Enter the email address you created the app password for in step 3
SMTP Password Enter the app password you created in step 3

When you have entered everything, the Mail Settings section should look like this:

Configuring SMTP Mail Settings in Joomla 3.X - The image shows the configuration fields and values for getting SMTP mail to work on Joomla 3.X with a GSuite email address. Note the SMTP Port is 587 and not 25 (or anything else).

Important step: Before being enticed to click the Send Test Mail button, click the green Save button on the top-left of the screen:

Saving your new Mail Settings - Make sure to click the green Save button on the top toolbar before running a test.

Once you click save, you should see a confirmation message that says “Message: Configuration successfully saved” in a green box.

Confirming saved changes to Mail Settings - When you save your settings you should see a green box with a success message.

Now we are ready to scroll down to the Mail Settings area again and click Send Test Mail.

Testing your new Mail Settings - Click the Send Test Mail button at the bottom of the Mail Settings section in the admin panel.

From here, you should see the following success message indicating that the email was sent (hopefully anyway):

Joomla 3.X SMTP test mail success messages - The Joomla system message should appear, indicating that a test email was successfully sent.

Then, you should log into the email account and verify that the email was actually sent. You are now testing to ensure that your settings worked.

Once you see the email, it should not show the padlock icon and phishing warning label; and the from label should be the email address you set up (as shown below):

Successful SMTP email sent from Joomla - If you did everything correctly, the test email should come to you within a minute and have your email address as the from field. Notice that there is no padlock warning or phishing label anymore either! Source: Gmail screenshot.

Clicking the little down arrow Gmail down arrow next to “me” should show you the exact details of the sender:

Confirming sender information in Gmail - If you click the little down arrow next to "me" you will see additional sender information, confirming that Gmail recognizes your Joomla website as the authentic mailer for your emails. Source: Gmail screenshot.

If you did everything correctly, the email address and from name should be what you entered into your settings.

If this worked for you, then congratulations on setting it up! You are done.

If you didn’t make it to the success portion, check out the next troubleshooting section.

Troubleshooting Joomla’s Mail Settings with SMTP

If something didn’t work, then do not worry quite yet. Depending on your hosting company and/or other custom settings, it may take some tuning to get it to work. The following section outlines common root causes of failure, the reason(s) behind it, and recommended solutions.

Issue 1: Joomla error: “Notice: SMTP Error: Could not Authenticate”

You may see a blue message label saying that SMTP could not be authenticated.

Joomla SMTP mailer authentication error - If you entered the SMTP credentials incorrectly you may receive an error in blue saying that there was a problem. To fix it, check your credentials and try again.

Problem: Something is wrong with the SMTP settings. You most likely entered the wrong username or password.

Solution #1 - Check Mail Settings: Check that your Mail Settings are entered correctly with the right values. Remember that the SMTP password field must be the app password you created in your Google account settings, not your GSuite password.

Solution #2 - Spaces in SMTP Password: This problem didn’t happen to me (even after testing and trying to break it), but you may have entered everything correctly in the Mail Settings, but it still does not authenticate.

It’s possible that when you entered the app password you included spaces. If you recall from step 3, the app password Google provided you had spaces in it:

Spaces in Google’s app password - When you created your Google app password, remember that it had spaces. These spaces could be pasted into the Joomla SMTP mail settings and result in an authentication error. Source: Google account screenshot.

You may have pasted the password with spaces. I recommend pasting the password in a text editor (like Notepad) and then checking to see if the spaces are there. If they are, just remove them and try the authentication again.

Issue 2: Joomla gave me a success message but I didn’t get the email

You may see a success message, but no email was sent.

Problem: You may have to try entering a different SMTP Port.

Solution - Use Port 25 instead: Try using port number 25 instead of 587, save it, and send a test email again. Note that Joomla’s hover help tooltip under 'SMTP Port' says to use port 465 to secure SMTP. I tried this and it didn't work. Stick with 25 or 587.

Issue 3: Joomla gave me an “SMTP connect() failed” error message after a few minutes

If you tried to send a test email and “nothing happened,” you may see a Joomla error after a few minutes (on the admin backend): “Notice: SMTP connect() failed. https://github.com/...”. The error will be in blue.

Joomla “SMTP connect() failed” error - An SMTP connect error like the one pictured above could result from using the wrong port (like 465). Try using port 587 (or 25) and test it again.

Problem: If you see this, you most likely entered the incorrect port number (like 465).

Solution - Use Port 587: Try port 587 (or 25) instead.

Issue 4: I tried everything and it still just doesn’t work!

If you followed the guide, exhausted the troubleshooting guidance here, and it still doesn’t work for you, you have one more option. You may have to enable “less secure” apps to work with your GSuite account.

Problem: By default, Google protects your GSuite account by blocking apps that it thinks are less secure. You don’t get to see which ones they block or how often it happens (I think?), but you can turn off this default protection through the Google Admin panel.

If you want to learn more about why Google does this, you can read their help article on it.

Solution #1 - Enable “less secure apps”: Go to Google account > Less secure apps and enable less secure apps to work with your GSuite account. Now, if you have two-step authentication turned on it won’t let you do this, so it might not work at all.

But this solution may work if you are using a different (older) version of Joomla or you have a different GSuite release (yes, different organizations have different releases based on their settings and other factors). I have used this setting to make the mailer work on older versions of Joomla. But be warned, Google doesn’t recommend it so use it at your own risk.

Solution #2 - Leave a comment and I will try to help: Leave a comment at the bottom of this page and tell me about your problem. Please be specific and if you prefer, please reach out to me using my contact form and provide more precise details (attachments like images).

I can’t promise to make it work for you, but I will try and help.

Solution #3 - Create a new thread on the Joomla forums: If all of these steps have failed you, then I recommend going to the Joomla Forums > Administration 3.X section and creating a new thread. The community can be very helpful.

Before doing so, I recommend reading the forum rules and running the Forum Post Assistant script so that the community can help you more quickly.

Help me improve this guide

If you liked this guide, consider helping me improve it by leaving a comment at the bottom. If there was a mistake or something didn’t work correctly, let me know as well so that I can update this guide for other people to use.

Specifically, if you experienced an error (troubleshooting item) that I didn’t list, feel free to send it to me and I will include it in this article (with attribution to you of course).

If you liked this post and would like other useful ones, please consider signing up for my email newsletter and .

Links and trademarked logos disclaimer

i bobandedovic.com (my website) is not affiliated with or endorsed by the Joomla!® Project or Open Source Matters organization. The Joomla!® name and logo is used under a conditional use logo license found on joomla.org. I claim no rights over it.

ii Google®, GSuite® (formerly Google Apps for Work®), its logos/marks, and all references to Google's productivity software include images that I do not own. I claim no rights, association, or partnership with Google. All references are for information purposes only.

iii The external links to Google are not affiliate links and I do not make any compensation for having them on this blog post.

Tags

TechnologyJoomla 3.XJoomla mailerGSuitetwo-step authenticationSMTPGoogle for WorkGoogle AppsJoomlahow-to

Comments

Ismail Jun. 18, 2017 4:44 AM
Very Informative,I am trying to fix this but still I am getting error, Can you help me please
Reply

Comment options

Report comment
Boban Dedovic Jun. 18, 2017 4:04 PM
Ismail, thanks for reading the guide and posting a comment. It can be a bit tricky to set this up, and I am happy to help you. I will send you a personal email and see if I can help. Thanks!
Reply

Comment options

Report comment

Add comment

Join the conversation, but please make sure to show respect to others. Read the comment policy before posting.

Comment policy

Before posting a comment, please make sure to read the following rules.

  • No cussing
  • No hate speech or otherwise abusive behavior towards others
  • No spam or offensive material (like pornography)
  • Don't add links to malicious websites
  • You are responsible for what you write and agree to hold harmless bobandedovic.com in the case of any damages that result from your comments
  • You grant bobandedovic.com a royalty-free (and irrevocable) license to post, re-use and distribute your comments in any format (worldwide)

Comments may be removed without notice at the moderator's discretion.

Share this page

Share this page

Categories

Blog categories

Subscribe