How to Set Up the Gmail Mailer in WP Mail SMTP

Would you like to use your Gmail or Google Workspace (formerly G Suite) account to fix email delivery issues on your site? WP Mail SMTP’s Gmail option uses Google’s API to securely authenticate your site’s emails, helping them to get delivered successfully.

In this tutorial, we’ll show you how to set up WP Mail SMTP using the Google mailer with your Gmail or Google Workspace email address.

  1. Installing and Configuring the WP Mail SMTP Plugin
  2. Creating a Web App in Your Google Account
  3. Updating the Publishing Status From Testing to Production
  4. Granting Permissions and Sending Test Email
  5. Frequently Asked Questions

1. Installing and Configuring the WP Mail SMTP Plugin

Before getting started, you’ll need to install and activate the WP Mail SMTP plugin.

Once you’ve got the plugin installed, you’re ready to configure the plugin’s settings. You can find these settings in WP Mail SMTP » Settings, under the General tab.

General tab SMTP settings

Below, we’ll cover the settings needed for this setup.

From Email

This is the email address that all of your site’s emails will be sent from. Once you’ve connected your Gmail account, you can select the email address you’d like to use (including any aliases you’ve configured) from the dropdown that appears.

Note: In order to use multiple Gmail aliases throughout your WordPress site as the From Email address, make sure the Force From Email box is left unchecked.

From Email in WP Mail SMTP settings

From Name

Below the From Email, you can set the From Name. This is the name associated with the emails your site sends out. By default, this will be set to your site’s name, but you can adjust this to any value you’d like.

You can also check the Force From Name option to apply this setting site-wide.

From Name in WP Mail SMTP settings


This is where you can choose which mailer you’d like your site to use. To configure the Gmail mailer, you’ll need to select the Gmail option.

Select Gmail mailer

Once you’ve chosen this mailer, you should see a new section appear titled Gmail. In this section, there are settings named Client Secret and Client ID.

Client ID and secret settings

To generate the information needed for these fields, you’ll need to use your Google account to create a web application. This process doesn’t require any coding, and we’ll show you exactly what to do in the next step.

We’ll be coming back to WP Mail SMTP’s setting page a little later, so for the next step you’ll need to open a new tab or window in your browser.

2. Creating a Web App in Your Google Account

In the new tab or window you’ve opened, you’ll need to log into your Gmail account and access Gmail’s application registration.

Note: Before continuing, be sure to sign out of all other Google accounts besides the account you’ll be using for the SMTP setup.

Also, if you’re using Google Workspace, make sure that the Google account you use has permission to send emails (in other words, access to its own inbox).

If it’s your first time using Google Cloud Console, you may be asked to agree to the Terms of Service. Go ahead and agree to the Terms of Service, and select your country from the Country of residence dropdown menu.

After you’ve configured each of these settings, go ahead and click the Agree and continue button to move on to the next step.

Click agree and continue button

If you’ve logged into the Google Cloud Console before, you’ll likely bypass the Terms of Service. Instead,  you’ll see a form named Register your application for Gmail API in Google Cloud Platform.

Register your application

For the Select a project where your application will be registered step, a new project will automatically be created for you in Google if you haven’t previously created one. Click on the Continue button.


Once you’ve completed either of the steps above, you’ll see a confirmation message that says The API is enabled. To move forward to the setup page, go ahead and click the Go to credentials button.

Gmail API is enabled

Creating Your Application’s Credentials

On the next page, you’ll be asked a few questions to help Google determine the Credential Type you need.

Credential type Google Cloud Platform

In the Select an API dropdown menu, make sure the Gmail API is selected.

Note: If you don’t see an option for the Gmail API in the dropdown, be sure that you have the Gmail API enabled for your account.

Select Gmail API

Next, under the What data will you be accessing? section, select the User data option. Then, click the NEXT button to proceed to the next step.


In this second step, Google will ask for some basic App information.

OAuth consent screen

This section is more for personal use, since nobody else will be using your app. However, some fields are still marked as required:

  • App name: Input the app name of your choice, for example: Pattie’s App
  • User support email: Select your email address
  • App logo: If you’d like, you can upload a logo for your app

Finally, add your email address in the Email addresses field. Then, when you’re ready, click on the SAVE AND CONTINUE button to proceed to the next step.

Click save and continue button

Configuring Scopes (optional)

This is an optional step that we will be skipping for this tutorial. Scroll down to the end of the Scopes section and click on the SAVE AND CONTINUE button to proceed.

Setting Up Your OAuth Client ID

Next, we’ll need to fill out some information about our OAuth Client ID.

In the Application type dropdown menu, select the Web application option. Once you select this option, more fields will populate.

Select web application

Now, you can leave the Name field as the default value or change it to something more relevant. For this example, we’ll leave the default name, Web client 1.

OAuth name

Next, go ahead and skip the Authorized JavaScript origins section and scroll to Authorized redirect URIs.

Then, click on the  + ADD URI button and input the following:

Input for URI

When you’re ready, click on the CREATE button to complete this step.

Click create button

At this point, you are done with the Create credentials setup and should see your Client ID on the Your Credentials page.  Don’t worry about saving or copying the Client ID, we’ll do that a bit later.

Go ahead and click the DONE button at the bottom of the page.

Click done button

Updating the Publishing Status From Testing to Production

Note: This step is only for users with free Gmail accounts. Users with Google Workspace accounts should skip this step.

Google will put your app into testing mode by default. It’s really important that you switch to the production mode, otherwise, your app will be super limited and will not function properly.

From the Google Cloud Platform dashboard, locate the menu on the left side, and click on the  OAuth consent screen option.


In the Publishing status section, you will see that the app is in Testing mode. Click on the PUBLISH APP button to switch it to production mode.

Publish app Google API

Now, a modal will appear stating that Your app will be available to any user with a Google Account.

Don’t worry, you are the only one that will have access to this app. This app will only be used in your WordPress site (in the admin dashboard area). To continue, click on the CONFIRM button.

Push Testing app to Production

Once confirmed, you’ll see that your app’s Publishing status is now In production.


3. Granting Permissions and Sending Test Email

Next, in the left side menu click the Credentials option.

Credentials menu option

Once you’re on the Credentials page, in the OAuth 2.0 Client IDs section you can see the details of the web application you just created. To view the Client ID and Client Secret, click the pencil icon.

Click pencil icon

This will open all of the details for your app. On this page, you’ll see the Client ID and Client secret values.

Client ID and client secret

Go ahead and copy both of these values into the corresponding fields of your WP Mail SMTP settings.

Client ID and Client Secret in Gmail Mailer

Note: Be very careful not to copy any extra text or spaces with your Client ID or Client Secret, as this will result in an error in the next step.

Once those have been added, click the Save Settings buttat the bottom of the page.

Save settings button

After saving these settings, the page will refresh. You must grant permission before Google allows our plugin to use your Gmail API to send emails.

To do this, scroll to the bottom of this page and click the button labeled Allow plugin to send emails using your Google account.

Authorize plugin to send emails with Gmail

This will open a login screen for Google. Go ahead and log into the account you’re setting up SMTP with.

If you are connecting with a free Gmail account you might see the below screen. Google Workspace users will not see it because their app is configured for internal use only, a setting, which is not available for free Gmail users.

Go ahead and click on the Advanced link in the bottom left corner.

Gmail OAuth warning

In this expended section click on Go to (unsafe). Don’t worry, Google only displays this warning, because the app is not verified by them. There is no need for the app to be verified since you created this app just for your own use.

Gmail OAuth show advanced

Next, you’ll see a screen asking for permission for this site to send emails on your behalf.

When you’re ready, click the Allow button to proceed.

Provide permissions to Google app

Next, you’ll be returned to your WP Mail SMTP settings and a success message will be displayed. Now that the connection is complete, you’re ready to send a test email. To do this, navigate to WP Mail SMTP » Tools and open up the Email Test tab.

Email Test tab in WP Mail SMTP

Once the Email Test tab is open, you’ll need to enter a valid email address and click the Send Email button. Be sure to use an email address you have access to so you can confirm the email is delivered.

Click send email button

When the test message has been sent, you’ll see a success message at the top of this tab.

WP Mail SMTP test email success message

You should also soon receive a test email at the email address you entered.

Successful test email from WP Mail SMTP

Frequently Asked Questions

What If the Test Email Doesn’t Send Successfully?

If the SMTP test email isn’t able to send, a debug log will appear with additional details. Here are some of the possible error messages and how to resolve them.

401. That’s an error.
Error: invalid_client

This error appears when the Client ID isn’t able to be read properly. To fix, try copying the Client ID in again and check that there’s no whitespace or extra text.

400. That’s an error.
Error: invalid_request
Missing required parameter: client_id

This error will display when the Client ID field is empty or not able to be read properly. To fix, copy in the Client ID again and be careful to not add extra text or whitespace.

cURL error 60: SSL certificate problem
This message means that the server is missing a certificate that’s required for SMTP to work. To fix this, you’ll need to contact your site’s hosting provider to ask them to install this certificate (most likely the cacert.pem certificate, though it’s best to ask your host to check).

“code”: 401,
“message”: “Login Required”

If you see this in the debug message, permission still needs to be granted to your Google account. For instructions on how to fix this, please see Step 3 of this tutorial. Also, be sure to check that the From Email in your SMTP settings matches the email used to setup the Google app.

Request Entity Too Large
Error 413

If you’re seeing this error, it’s likely that files being sent through your forms exceed Gmail’s limit for direct file attachment in emails. This limit is applied to the sum of the message’s text as well as the encoded attachment. To prevent this error, you’ll need to make sure that all files are no larger than 22 MB.

There was a problem while retrieving Auth for gmail: Could not json decode the token

This error is a possible indicator that another plugin (such as UpdraftPlus) is loading a different version of Google’s API on the site, creating a conflict. If possible, the conflicting plugin should be deactivated. Otherwise, it’s recommended that you set up another mailer.

If none of the above apply, or the test email still isn’t working:
Your Google account may have the Gmail API disabled. To check on this, follow Google’s guide to enabling an API.

If the Gmail API is enabled, after following those steps you should see a small green checkbox labeled API enabled.

Check that Gmail API is enabled

What If I See a Screen Saying “This app isn’t verified”?

When you click the Allow plugin to send emails using your Google account button, Google might display a screen that says “This app isn’t verified. This app hasn’t been verified by Google yet. Only proceed if you know and trust the developer.” There’s no need to worry, though — the message is only referring to the app that you just created in your own Google account (so you are actually the developer in this case).

To bypass this message, you’ll need click Advanced and then Proceed.

This app isnt verified error

What If I Want to Switch to A Different Email Later?

If you’d like to change to a different Gmail or Google Workspace email address, you’ll need to repeat all tutorial steps above. This includes generating a new Client ID and Client Secret under this other email account.

When you get to the Authorization step (under Step 3), save your settings and then click the Remove Connection button. This will remove the authorization for your original email account and allow you to repeat the authorization steps with the new email.

Remove connection in WP Mail SMTP

Does the Gmail Mailer Support Aliases?

Yes, as of July 2020, Gmail aliases are supported in WP Mail SMTP. For more details on how to set up an alias in Google, check out their guide on how to send emails from an alias.

Can I use this if I have 2 Factor Authentication (2FA) enabled on my Google account?

You can definitely use 2 Factor Authentication with WP Mail SMTP’s Gmail option. However, it’s important to note that if you choose to disable 2FA, or change the password on your account, you’ll need to go through the setup process again.

When authorizing my app, I get the following error message:

Error 403: access_denied. The developer hasn’t given you access to this app.

This message means that your app’s permissions are set to the testing mode in the Google app.

To fix this, be sure to switch the mode for testing to production and try authorizing your app one more time.

Do I need to submit my app to Google for verification in order for it to work with WP Mail SMTP?

It isn’t required for you to submit your app for verification, however, you’re welcome to if you’d like. If you choose to submit your app for verification, you can continue the authorization process in WP Mail SMTP, without waiting for Google’s verification.

That’s it! You’ve now set up WP Mail SMTP’s Gmail mailer on your WordPress site.

Next, would you like to know how to effectively troubleshoot issues within WP Mail SMTP? Be sure to check out our tutorial on troubleshooting WP Mail SMTP for more details.