How to Set Up Gmail on XFile Ultra
Gmail mode sends mail through Google using OAuth (XOAUTH2). You do not paste your Gmail password into the script. You create a Google Cloud OAuth client, then click Connect Google once.
Best for low volume (personal / small sites). For high volume, prefer SMTP with a transactional provider.
Where to find it
Admin → Settings → Main (Settings tab) → Email delivery
1. Set Email delivery mode to Gmail
2. Fill Google account, Client ID, Client secret
3. Copy the shown Redirect URI into Google Cloud
4. Save
5. Click Connect Google and finish consent
6. When status is Connected, click Send test email
Also set Email from address to the same Gmail address (or an address that Gmail account is allowed to send as).
Fields explained
| Field | What it is |
|---|---|
| Google account | The Gmail address that will send mail (example: you@gmail.com or a Google Workspace address) |
| Redirect URI | Read-only URL shown in admin — paste this exactly into Google Cloud |
| Client ID | From Google Cloud OAuth client |
| Client secret | From Google Cloud OAuth client (leave blank on later saves to keep the stored secret) |
| Connection | Connect Google / Disconnect / Send test email |
Redirect URI shape:
https://YOUR-DOMAIN/api/admin/settings/email/gmail/oauth/callbackUse your real public site URL (HTTPS). It must match what Google has, character for character (no extra slash, wrong http/https, or different domain).
Step 1 — Create the OAuth client in Google Cloud
1. Open Google Cloud Console
2. Create or select a project
3. Go to APIs & Services → Credentials
4. Click Create credentials → OAuth client ID
5. If asked, configure the OAuth consent screen first (see Step 2)
6. Application type: Web application
7. Under Authorized redirect URIs, add the exact Redirect URI from XFile Ultra
8. Create the client
9. Copy Client ID and Client secret
Step 2 — OAuth consent screen (important)
In APIs & Services → OAuth consent screen:
1. Choose External (unless you only use Google Workspace internal users)
2. Fill App name, User support email, and Developer contact
3. Add App domain / links if Google asks for them:
- Homepage
- Privacy policy
- Terms of service
4. Save
Google often requires privacy policy and terms URLs before you can publish or before some users can connect. Use your real site pages (example: https://example.com/privacy and https://example.com/terms).
Publishing status
- Testing — only test users you add can connect. Add your Gmail as a test user.
- In production (published) — any Google account can complete consent (subject to Google’s verification rules for sensitive scopes).
If Connect fails with “access blocked” for your own account, you are probably still in Testing without that account on the test-user list — or the app is not published.
Step 3 — Fill XFile Ultra and Save
1. Mode Gmail
2. Google account = the mailbox that will send
3. Paste Client ID and Client secret
4. Confirm Redirect URI matches Google Cloud
5. Click Save (do this before Connect)
Connect needs the saved client ID/secret on the server.
Step 4 — Connect Google
1. Click Connect Google
2. Sign in with the same Google account
3. Approve access (mail send scope)
4. You return to admin; status should show Connected
5. Click Send test email
The script stores a refresh token after a successful connect. You do not paste that token by hand.
“This app isn’t verified” / “not safe” warning
During Connect, Google may show a warning like the app is not verified or is unsafe.
That is normal for a new OAuth client you created yourself.
What to do:
1. Click Advanced (or similar)
2. Click Go to … (unsafe) / continue to your app name
3. Approve the permissions
You are the developer of this OAuth client for your own site. For a private/admin-only connect flow, continuing as the developer is expected.
Later you can submit the app for Google verification if you need broader production use. For a single admin mailbox, Testing + your account as test user is often enough.
Checklist
| Item | Done? |
|---|---|
| Redirect URI in Google Cloud matches admin exactly | |
| Client ID + secret saved in XFile Ultra | |
| Consent screen has app name + support email | |
| Privacy / Terms URLs added if Google requires them | |
| App published or your account is a test user | |
| Clicked Connect Google and finished consent | |
| Status shows Connected | |
| Test email received |
Common problems
Redirect URI mismatch
Google Cloud URI must match the admin value exactly. Copy-paste from the read-only field. Common mistakes: http vs https, www vs bare domain, trailing slash.
Access blocked / app not verified
Add yourself as a test user, or publish the consent screen. Add privacy/terms if Google asks.
“Gmail is not authorized yet”
Client ID/secret saved, but Connect Google was never completed (or was disconnected). Connect again.
Connected, then mail stops later
Refresh token revoked, client secret rotated, or mail scope missing. Disconnect, update secret if needed, Save, Connect Google again and accept all permissions.
Wrong Google account connected
Disconnect, set Google account to the correct address, Save, Connect again with that account.
From address rejected
Set Email from address to the connected Gmail (or an alias / Workspace address allowed for that account).