Connect Gmail with OAuth.

01 How it works

Lean SMTP uses the OAuth 2.0 authorization-code flow against an OAuth client you create in your own Google Cloud project. You click Connect in the plugin, approve access in the Google consent screen once, and Google hands back a refresh token that the plugin stores encrypted. On each send it trades that refresh token for a one-hour access token and posts the message to the Gmail API — the same send path as the service-account transport.

The connected mailbox is captured automatically from the sign-in (the openid email scopes), so you never type the sending address.

02 Before you start

• A Google Workspace account that can send mail — the mailbox you'll connect, e.g. noreply@example.com.
• Access to a Google Cloud project owned by that Workspace organization. The "Internal" consent-screen option only appears for projects under a Workspace org. (You do not need to be a Super Admin — that's the whole point versus the service-account method.)
• Lean SMTP 0.6.0 or newer installed and activated.

03 Create a project & enable the Gmail API

In the Google Cloud Console, create (or pick) a project that belongs to your Workspace organization. Then open the Gmail API page and click Enable.

04 Set the consent screen to Internal

Open Google Auth Platform → Audience. The User type must be Internal. If you've never configured the consent screen, you'll be prompted to create it first (give it an app name and a support email) — choose Internal as the audience.

05 Get the redirect URI from Lean SMTP

You'll need the plugin's callback URL when creating the OAuth client. In WordPress, go to Settings → Lean SMTP, set the mailer to Gmail / Google Workspace (OAuth), and copy the read-only Redirect URI shown there. It looks like:

https://your-site.com/wp-admin/admin-post.php?action=lean_smtp_gmail_oauth_callback

06 Create the OAuth client (Web application)

1. Open Google Auth Platform → Clients and click Create client.
2. Set Application type to Web application.
3. Give it a name, e.g. lean-smtp.
4. Under Authorized redirect URIs, click Add URI and paste the Redirect URI from Step 5.
5. Click Create.

07 Copy the Client ID and secret

Google shows the new client's Client ID and Client secret once. Copy both now (the secret isn't shown again — though you can always add a new secret later).

08 Connect in Lean SMTP

1. Back in Settings → Lean SMTP with the mailer set to Gmail / Google Workspace (OAuth), paste the Client ID and Client Secret.
2. Click Save Changes. A Connect a Google account button appears in the Connection row.
3. Click Connect a Google account. You're sent to Google — sign in as the mailbox you want to send from and approve the request.
4. You're returned to the settings page showing Connected as you@example.com. That address is captured from the sign-in automatically.
5. In the From section, set From Email to the connected address (or an alias it may send as), and enable Force From if other plugins set their own.

09 Configure in wp-config.php (optional)

The client ID and secret can be pinned as constants, which beat the stored options and lock the fields in the admin. The refresh token and connected mailbox come from the Connect flow, so they're not set this way:

define( 'LEAN_SMTP_MAILER', 'gmail_oauth' );
define( 'LEAN_SMTP_FROM_EMAIL', 'noreply@example.com' );
define( 'LEAN_SMTP_GMAIL_OAUTH_CLIENT_ID', '1234567890-abc.apps.googleusercontent.com' );
define( 'LEAN_SMTP_GMAIL_OAUTH_CLIENT_SECRET', getenv( 'LEAN_SMTP_GMAIL_OAUTH_SECRET' ) );

10 Send a test email

• Use the Send a Test Email button on the settings page, or
• Run WP-CLI:

$ wp lean-smtp test you@example.com

Success: Test email sent to you@example.com.

wp lean-smtp status shows the mailer, the client ID and whether an account is connected — never the secret or refresh token.

11 Troubleshooting

12 Which method should I use?

Both use the same Gmail API and the same send path. See the service-account guide for that method.

13 Security notes

• Least privilege. The grant is scoped to gmail.send (plus openid email to read the address) — send only, no inbox access.
• Encrypted at rest. The client secret and refresh token are AES-256 encrypted against your site salts and never re-displayed.
• Revoking is one click. Disconnect in Lean SMTP revokes the grant at Google and forgets it locally. You can also remove it from the account's third-party access.
• Rotate the secret in the Google Cloud client if it may have leaked, update it in the plugin, and reconnect.