Gmail / Google Workspace OAuth Setup

Connecting Gmail or Google Workspace mailboxes to MailTrixy uses Google OAuth 2.0. Tokens refresh automatically — users connect once and never have to re-enter credentials. This is a one-time admin setup; after it's done every user connects their own Gmail with a single click.

Exact redirect URL (the one you paste in Google Console)

Google requires you to register the redirect URL exactly as MailTrixy will use it. Replace YOUR-DOMAIN with your real domain:

https://YOUR-DOMAIN/email-oauth/google/callback

Example: if your install runs at https://app.acme.com, the redirect URL is:

https://app.acme.com/email-oauth/google/callback

Google is strict about the redirect URL match:

  • Must be HTTPS (only http://localhost works for HTTP).
  • No trailing slash. /callback not /callback/.
  • Exact case — all lowercase.
  • Exact path — /email-oauth/google/callback.
  • If your APP_URL in .env doesn't include https:// the redirect won't match. Always set APP_URL=https://your-domain.com in production.

How the OAuth flow works

  1. Admin (one-time): creates a Google Cloud project, enables the Gmail API, builds an OAuth Client ID, and pastes the Client ID + Secret into MailTrixy.
  2. User (every workspace): opens Settings → Email Accounts → clicks “Sign in with Gmail”.
  3. Google's consent screen opens. User signs in, grants read/send permissions.
  4. Google redirects the browser to the redirect URL above with a one-time authorization code.
  5. MailTrixy exchanges that code for an access token + refresh token. Tokens are encrypted and stored in the database.
  6. MailTrixy calls the Gmail API (mail.google.com) to sync messages and send replies. Tokens auto-refresh before expiry — no manual intervention.

Step 1 — Create a Google Cloud project

  1. Open console.cloud.google.com and sign in with the Google account you want to own the OAuth app.
  2. Click the project dropdown at the top → New Project.
  3. Project name: MailTrixy (or your platform's name). Leave the organisation field default. Click Create.
  4. Wait ~10 seconds for the project to be created, then make sure it's selected in the top dropdown.

Step 2 — Enable the Gmail API

  1. Left menu → APIs & Services → Library.
  2. Search for Gmail API.
  3. Click the result, then click Enable. Wait ~15 seconds for the API to enable.

Step 3 — Configure the OAuth consent screen

  1. Left menu → APIs & Services → OAuth consent screen.
  2. User Type: pick External (unless you're using Google Workspace and want to restrict to your domain only). Click Create.
  3. Fill in the App information:
    • App name: your platform's name (e.g. “MailTrixy” or “Acme Corp”) — this is what users see on the consent screen.
    • User support email: your support email.
    • App logo: upload your brand logo (square, recommended).
    • Application home page: https://YOUR-DOMAIN
    • Application privacy policy: https://YOUR-DOMAIN/privacy
    • Application terms of service: https://YOUR-DOMAIN/terms
    • Authorized domains: add YOUR-DOMAIN (just the bare domain, no https://).
    • Developer contact email: your email.
  4. Click Save and Continue.
  5. On the Scopes page click Add or Remove Scopes. Search and add these four scopes:
    • https://mail.google.com/ — full Gmail read/send (this is the master Gmail scope)
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/userinfo.email
    Click Update → Save and Continue.
  6. On the Test users page, add the Google accounts you'll use to test the connection (until your app is verified, only listed test users can sign in). Click Save and Continue.

Note on app verification: until Google formally verifies your OAuth app (a free process that takes a few weeks for sensitive scopes), only test users you've added here can sign in. For private deployments this is fine. For public SaaS, submit for verification once everything works.

Step 4 — Create the OAuth Client ID

  1. Left menu → APIs & Services → Credentials.
  2. Click + Create Credentials → OAuth client ID.
  3. Application type: Web application.
  4. Name: MailTrixy Web Client.
  5. Under Authorized JavaScript origins add: https://YOUR-DOMAIN
  6. Under Authorized redirect URIs click + Add URI and paste exactly: 
    https://YOUR-DOMAIN/email-oauth/google/callback
  7. Click Create.
  8. A modal pops up showing your Client ID (long string ending in .apps.googleusercontent.com) and Client Secret. Copy both, or click Download JSON to save them.

Step 5 — Paste credentials into MailTrixy

  1. Log into MailTrixy as super admin.
  2. Go to Admin → Settings → Integrations.
  3. Find the Google section.
  4. Paste the Client ID into the Google Client ID field.
  5. Paste the Client Secret into the Google Client Secret field (encrypted at rest).
  6. Click Save.

Step 6 — Test the connection

  1. Log out of admin or open an incognito window. Log back in as a workspace user.
  2. Go to Settings → Email Accounts → Add Account.
  3. Click the Sign in with Gmail button (red Google logo, marked PREFERRED).
  4. Google's account chooser appears. Pick the Gmail account you want to connect (must be a Test User you added in Step 3 unless your app is verified).
  5. The consent screen lists the permissions MailTrixy is requesting. Click Allow.
  6. You're redirected back to MailTrixy with a green “Gmail connected successfully!” message. Initial inbox sync begins automatically.

Troubleshooting

“Error 400: redirect_uri_mismatch”

The redirect URL Google received doesn't match anything you registered in Step 4. Check:

  • HTTPS (not HTTP) — unless localhost.
  • No trailing slash. /callback not /callback/.
  • Exact path /email-oauth/google/callback.
  • The exact domain matches your APP_URL in .env. Run php artisan config:clear after editing .env.
  • You clicked Save in the OAuth client ID edit screen after adding the URL.

“This app isn't verified” warning

Expected for unverified apps. Test Users (added in Step 3) can click “Advanced → Go to MailTrixy (unsafe)” to proceed. For production / public SaaS, submit the app for Google verification (free, takes 1–6 weeks for restricted scopes like full Gmail).

“Access blocked: MailTrixy has not completed Google verification”

Your Gmail account isn't on the Test Users list. Add it: Google Console → OAuth consent screen → Test users → +Add Users.

Connection works but disconnects after an hour

Google isn't returning a refresh token. Causes:

  • The OAuth request didn't include access_type=offline + prompt=consent. MailTrixy sets these by default — if you customised the OAuth controller, make sure they're still there.
  • The user previously authorised the same app and Google is reusing the old grant without a fresh refresh token. Have them revoke access at myaccount.google.com/permissions and re-connect.

“invalid_client” error on callback

The Client Secret in MailTrixy doesn't match Google Console. Re-copy the secret from Step 4 (Google Console → Credentials → click your OAuth client → Client secret). If you've lost it, create a new secret in the same screen and update MailTrixy.

Alternative: Gmail App Password (no OAuth)

If you don't want to set up OAuth at all, Gmail also supports IMAP with an App Password. This is less secure (passwords stored in DB) and slower, but skips the Cloud Console setup entirely.

See the “Gmail (IMAP/SMTP)” preset in Settings → Email Accounts → Add Account. Users will need to enable 2FA on their Google account and generate an App Password at myaccount.google.com/apppasswords.

Last updated 28/05/2026