Connecting Gmail or Microsoft 365 with OAuth2
Authorise the plugin to send through a Google or Microsoft mailbox without storing a password, using your own OAuth app.
- Advanced
- 20 min read
- Applies to 2.0
What this replaces
Sending through Gmail or Microsoft 365 used to mean putting a mailbox password — or an app password — into a settings field. Both providers have been closing that door: Google no longer issues app passwords for most Workspace configurations, and Microsoft has been turning basic authentication off tenant by tenant.
OAuth2 is the way in that remains. You register an application once, click Connect, and the plugin holds a token it can refresh instead of a password it must keep.
Only Gmail / Google Workspace and Microsoft 365 / Outlook support this flow. Every other provider — Resend, SendGrid, your host's server — authenticates with a username and a key, which is what those providers intend.
What you need first
- Administrator access to the WordPress site (
manage_options) - An account in Google Cloud Console, or in Microsoft Entra ID (Azure AD), for the domain that sends the mail
- The site reachable over HTTPS — both providers refuse plain-HTTP redirect URIs outside localhost
The plugin does not ship a shared application. You register your own, so the credentials, the consent screen and the quota are yours, and no third party sits in the path of your mail.
Step 1 — copy the redirect URI
Open User Access → Emails, choose Gmail or Microsoft 365, and copy the Redirect URI shown beside the provider. It looks like this:
https://yoursite.com/wp-admin/admin-post.php?action=attrua_oauth_callback&provider=gmailThe provider parameter is gmail or outlook. Register it exactly as shown —
providers compare it character for character, including the query string.
Step 2 — register the application
Google — in Google Cloud Console, create (or pick) a project, enable the consent screen for your organisation, then create an OAuth client ID of type Web application and paste the redirect URI into Authorised redirect URIs. Google issues a Client ID and a Client Secret.
Microsoft — in Microsoft Entra ID, register an application, add a Web platform with the same redirect URI, then create a client secret under Certificates & secrets.
The scopes the plugin requests:
| Provider | Scopes |
|---|---|
| Gmail | https://mail.google.com/, openid, email |
| Microsoft 365 | https://outlook.office365.com/SMTP.Send, offline_access, openid, email |
Google's narrower gmail.send scope is deliberately not used: it only works with
the Gmail API, not with SMTP over XOAUTH2, which is how mail actually leaves the
plugin. If your consent screen is restricted to gmail.send, the connection
succeeds and every send fails.
Step 3 — connect
Paste the Client ID and Client Secret into the provider's fields and save. The Connect Google Account (or Connect Microsoft Account) button becomes available.
Clicking it sends you to the provider's consent screen and back. On Google the plugin asks for offline access and forces the consent prompt every time, so a refresh token comes back on re-authorisation and not only on the very first one — a connection that silently stopped refreshing after a few weeks is the classic symptom of the opposite.
Sign in as the mailbox that should send the mail, not as your personal admin account, and make sure the From Email matches it.
How the tokens are held
Access and refresh tokens are written under
attrua_pro_email_settings[oauth_token][<provider>] and only by the OAuth
flow itself — the settings form strips that key from anything submitted, so a
saved settings page can never overwrite or leak a token. The plugin refreshes the
access token as needed; you do not have to touch it again.
Disconnect removes the stored tokens for that provider. The application registration on Google's or Microsoft's side stays, so reconnecting later is one click and no paperwork.
When it does not work
redirect_uri_mismatch— the URI registered with the provider differs from the one shown in the settings; copy it again rather than retyping- Consent succeeds, sending fails with an authentication error — the scope is too narrow (see the warning above), or the connected account is not the From address
- It worked, then stopped — the refresh token was never issued or was revoked; disconnect and connect again
- Nothing happens on Connect — the Client ID or Secret is empty or was saved with trailing whitespace
Confirm the result with Test SMTP Connection on the same page: it sends a real message through the connection you just authorised.
Next steps
Something missing or out of date? Tell support.