You want WordPress to send a password reset, a contact-form notification or an order email through a Gmail account. The confusing part is that “connect Gmail” can describe two different setups: an App Password used over SMTP, or a Google OAuth connection used with the Gmail API.
Lumo Mail SMTP supports both. This guide takes you from choosing the right provider card to checking a real message in the recipient mailbox. It also explains two easily missed details: a connection test is not always an authentication test, and a Google app left in Testing can lose its refresh token after seven days.
Scope of this walkthrough
The field names and sending behavior below were checked against Lumo Mail SMTP 2.17.3 source code and Google’s official documentation. The numbered panels below are graphically annotated captures of the real plugin interface in our permanent tutorial lab, with demonstration values. The cover and workflow overview are conceptual illustrations. We did not connect a live mailbox or claim an inbox-delivery test. Lumo Mail SMTP is our product.
Start here: choose one Gmail connection method
| Method in Lumo | What you need | How mail is sent |
|---|---|---|
| Gmail / Google (OAuth) | Google Cloud OAuth client, exact redirect URI and account permission | Gmail API over HTTPS |
| Gmail / Google Workspace | Eligible Google account, 2-Step Verification and an App Password | Authenticated SMTP: smtp.gmail.com, port 465, encrypted transport |
Google generally recommends a Google sign-in connection instead of App Passwords. However, OAuth is not automatically a least-privilege setup: the reviewed Lumo release requests a broad Gmail scope. Read the permission note below before choosing that route. If an organization manages the mailbox, ask its administrator which connection method is permitted.
Do not configure both routes at once just to make the test turn green. Start with one primary provider and keep the initial test easy to interpret. A later backup or queue is a separate configuration decision.
Before you start
Use a WordPress administrator account and an HTTPS website for a production connection.
Choose a dedicated sending mailbox you control. Do not start with an employee’s personal inbox if the website must keep working after that person leaves.
Have access to your Lumo installation ZIP and the license required by your edition.
Keep one mail-routing plugin active. Back up the old configuration before changing an existing SMTP setup.
Prepare a recipient mailbox you control for testing. Never put real passwords or tokens in screenshots or support messages.
Gmail is a reasonable option to evaluate for modest transactional traffic, but it is not an unlimited newsletter service. Google’s personal Gmail limits describe restrictions around daily messages and recipients; work and school accounts have different limits. Plan around your actual order volume, resets and notifications rather than treating a published maximum as guaranteed capacity.
1. Install Lumo Mail SMTP and open Providers
Download the plugin ZIP from your Lumo account. In WordPress, go to Plugins → Add Plugin → Upload Plugin, choose the ZIP, install it and activate it. Complete the license step if your edition requires one. Then open Lumo WP → Mail SMTP → Providers.
If you have not chosen a mail plugin yet, the Lumo Mail SMTP product page lists current editions and included features. The important choice for this tutorial is the provider card: Gmail / Google (OAuth) and Gmail / Google Workspace are different paths.
Real plugin panel, annotated for clarity. Choose the card matching your connection method.
2. Connect Gmail with OAuth
Workflow illustration. Use the current Google Console and the values displayed by your own WordPress installation.
Step 2.1 — Create or select the Google Cloud project
Open Google Cloud Console while signed in to the account that will manage the integration. Create a project for the website, or select an appropriate existing project. Give it a recognizable name so you can distinguish it from unrelated integrations later.
In APIs & Services → Library, find Gmail API and enable it for that project. Enabling an API makes it available to the project; it does not yet grant access to your mailbox. Google’s Workspace development overview separates project creation, API enablement, consent and credentials.
Step 2.2 — Configure the consent information
Open Google Auth platform. If this is a new project, complete the initial setup. Use Branding for the app name and support/contact details, Audience for who may use it, and Data Access to review the scopes. Older Console layouts may group these controls under OAuth consent screen.
Use a name that you will recognize on the Google consent screen, such as your website’s mail integration. Choose Internal only when your Workspace organization and intended users qualify. For an External app in Testing, add the intended sending account as a test user. Being the website administrator does not automatically put your Google account on that list.
Read the requested access
In Lumo 2.17.3, the Google scope is https://mail.google.com/. Google classifies this as restricted and describes access beyond sending, including reading and deleting mail. It is not a send-only permission. Review the consent screen and use an account appropriate for that access. Google recommends narrower scopes where possible; changing the plugin to use them needs a compatibility review, not just editing the Console form.
Consult Google’s Gmail scope reference for the permission categories. If the access is unsuitable for your organization, stop before authorizing it and use an approved integration. Publishing the Google app does not automatically satisfy Google verification requirements or remove an administrator’s restrictions.
Step 2.3 — Copy the redirect URI from Lumo
Back in Lumo WP → Mail SMTP → Providers, select Gmail / Google (OAuth). Locate the read-only Authorized Redirect URI field and copy it exactly. Do not substitute your home page or the URL of this tutorial.
The reviewed plugin builds this address with WordPress’s admin URL. A typical installation produces a URL with this shape:
https://your-site.example/wp-admin/admin.php?page=lumo-mail-smtp&action=oauth_callback
This is an illustration, not a value to paste unchanged. Your site might use a different domain, a subdirectory or another admin URL. HTTPS, hostname, path and query string must match the value Lumo uses. Copying the displayed field is safer than typing it.
Real local-lab interface with dummy credentials. Copy the redirect URI from YOUR website; do not copy the localhost example shown here.
Step 2.4 — Create a web OAuth client
In Google Cloud, open Google Auth platform → Clients → Create client. Choose Web application. Add the copied Lumo URL under Authorized redirect URIs and create the client. Do not use a Desktop app client or paste the callback into Authorized JavaScript origins; this plugin uses a server-side callback.
Copy the resulting Client ID and Client Secret into the matching Lumo fields. Store the secret securely. A Google API key is not a substitute for either field. Google’s credential setup guide explains the client types, while the Gmail server-side authorization guide explains the token exchange.
Step 2.5 — Save, connect and confirm the account
Save the provider settings, then use the Google connection button in the OAuth section. The reviewed interface saves those credentials before opening Google’s authorization page. Sign in to the mailbox you actually want WordPress to use, inspect the app name and permissions, and authorize only if they are expected.
If Google blocks the application or your administrator denies access, resolve that configuration or policy issue. Do not disable account protection to complete a tutorial. After returning to WordPress, check the connected-account identity and make sure Gmail / Google (OAuth) is the selected primary provider.
Step 2.6 — Avoid the seven-day Testing trap
Google documents that refresh tokens for External apps in Testing generally expire after seven days, with an exception for a small set of basic identity scopes. The broad Gmail scope requested here is outside that exception. That can explain a connection that works initially and then needs authorization again.
Before relying on the connection for production, review the app’s publishing status and applicable verification requirements. Reconnect after the appropriate configuration change if required. Do not promise permanent access: token revocation and account or organization policies can still invalidate it. See Google’s OAuth token-expiration documentation.
3. Alternative: connect Gmail with an App Password
Real plugin interface with demonstration values. Use your own eligible Gmail or Workspace account and its generated App Password.
Use this route only when your account offers App Passwords and the organization permits them. Google prefers Google sign-in where supported. An App Password is a separate credential for the application; it is not your normal Google password.
Step 3.1 — Create the App Password in your own account
Enable 2-Step Verification in your Google Account if it is not already enabled. Then open App passwords, sign in when asked, give the credential a descriptive name and create it. Copy the generated value into your password manager and the plugin’s password field, not into a public document.
If the option is missing, account policies, Advanced Protection or a security-key-only setup can be relevant. Ask your Workspace administrator rather than switching off protections. Google also revokes App Passwords when the account password changes. Its App Password help page covers availability and revocation.
Step 3.2 — Enter the two Gmail fields in Lumo
Open Lumo WP → Mail SMTP → Providers and choose Gmail / Google Workspace. Fill Gmail Address with the full address that owns the App Password. Put the generated credential in App Password, then save.
This specific provider supplies the SMTP host and transport settings itself. In the reviewed source they are smtp.gmail.com, port 465, encrypted SSL/TLS transport and SMTP authentication. You do not need to invent a host or port for this card. The generic SMTP provider is a different configuration screen.
The connection check has a limit
The reviewed Gmail App Password connection test opens a socket to Gmail’s SMTP endpoint after checking that required fields are present. It does not authenticate by sending a message. Even an incorrect App Password can coexist with a successful reachability test. Always continue to Send Test.
4. Set the sender and Reply-To correctly
Real General settings panel; Northstar Studio and sender@example.com are examples. The switches shown are the captured lab state, not a universal preset.
Open General and use the connected mailbox as your initial From Email. Set a recognizable From Name, such as the site name. If you force the sender across WordPress, check that it does not conflict with another intentional sending identity.
The App Password provider aligns the From address to the configured Gmail mailbox. The OAuth sender checks the account’s send-as addresses and can retain an allowed alias; otherwise it falls back to the connected mailbox. Typing an arbitrary company address into WordPress does not authorize Gmail to send as that address.
For a contact form, put the visitor’s address in Reply-To and keep your authorized mailbox in From. You can then reply to the visitor without pretending that their address is the sender. Test this explicitly by receiving the form notification and checking where Reply would go.
5. Send a real test and inspect the evidence
Real test-email form with an example recipient. No message was sent from the lab; follow the checks below on your configured site.
Open Lumo WP → Mail SMTP → Send Test using the header button or Test Email section.
Enter a recipient mailbox you control in Send To, then click Send Test Email. The plugin supplies the test-message content.
Check the plugin result and the corresponding entry in Email Logs.
Open the recipient mailbox, including spam. Confirm the message, sender and Reply-To.
Trigger the actual site workflow: a test form, a password reset for your test account, or an email from a test order.
For OAuth, the provider’s connection test retrieves a Gmail profile using a valid access token. That is a stronger account check than opening an SMTP socket, but it still does not prove delivery of a WordPress notification. Both routes need the final message test.
Keep queuing off while establishing your baseline unless the site already depends on it. If an email is queued, inspect the worker and cron behavior before concluding that Gmail rejected it. Our WordPress SMTP setup and troubleshooting guide explains the difference between queued, accepted, delivered and inbox placement.
6. Fix common Gmail connection problems
redirect_uri_mismatch
Copy Authorized Redirect URI from this installation again. Compare protocol, domain, path and the complete query string with the Google client.
Access denied during Google authorization
Check the selected Google account, test-user list, audience and Workspace policy.
App is unverified or blocked
Review the project, requested scopes and verification requirements. Do not assume every warning is safe to bypass.
Connection stops after about seven days
Check External + Testing status and token expiry before reinstalling the plugin.
App Password authentication fails
Use the generated App Password for the same Gmail Address, not the normal account password. Check whether it was revoked.
SMTP connection timeout
Ask the host whether outbound smtp.gmail.com:465 is reachable. A correct password cannot fix a blocked network route.
TLS certificate error
Resolve certificate trust or hostname problems with the host. Do not disable certificate verification.
Test reaches the mailbox but forms do not
Inspect the form’s recipient and notification trigger. Confirm it uses the WordPress mail path.
Email is sent from an unexpected address
Check the connected mailbox, forced From setting and whether the OAuth send-as alias is actually allowed.
Rate-limit or quota error
Inspect the account’s current limits and reduce or pause the workload. A queue or API connection does not remove Gmail’s sending limits. —
7. Know when Gmail is no longer the right fit
A small site sending occasional contact notifications has a different requirement from a busy store sending orders, refunds, resets and reminders throughout the day. Count those events before committing your entire mail workflow to a mailbox account.
Consider a dedicated transactional email service when you need higher sustained volume, clearer bounce and suppression handling, operational monitoring or separation from a person’s mailbox. Changing from App Password to OAuth solves an authentication choice; it does not turn Gmail into unlimited delivery infrastructure.
A final checklist before you leave the settings page
The selected provider matches the method you configured.
The authorized mailbox is the intended sender, and Reply-To behaves correctly.
A real test email arrived; a connection badge was not the only evidence.
The site’s actual notification workflow was tested with controlled data.
OAuth audience, publishing status and requested permissions were reviewed, or App Password availability and ownership were confirmed.
Someone knows how to reconnect the account or replace a revoked credential.
No secret or reset link appears in public screenshots, and log retention is intentional.
Sources and version notes
Reviewed October 24, 2026. Lumo source files inspected: GmailProvider.php, GmailOAuthProvider.php, GmailApiClient.php, OAuth.php, PhpMailerSender.php and the Providers admin view. Google documentation is linked beside the relevant instructions. Console labels and account policies can change; use the exact redirect URI and permission screen shown for your installation.
Originally published on LumoWP.
Top comments (0)