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.
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:
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 padlock warning next to the sender address.
- Gmail showed the dreaded “phishing scam” message
You can see a copy of the email below:
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.
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.
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.
Here, you should see a set of screens that walk you through the setup process of two-step verification:
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.
Next, enter the 6-digit code that you received from Google in the code box.
Once it’s confirmed, click TURN ON to finalize the setup.
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:
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)
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.
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.
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:
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.
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:
When you have entered everything, the Mail Settings section should look like this:
Important step: Before being enticed to click the Send Test Mail button, click the green Save button on the top-left of the screen:
Once you click save, you should see a confirmation message that says “Message: Configuration successfully saved” in a green box.
Now we are ready to scroll down to the Mail Settings area again and click Send Test Mail.
From here, you should see the following success message indicating that the email was sent (hopefully anyway):
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):
Clicking the little down arrow next to “me” should show you the exact details of the sender:
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.
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:
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.
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.