Gmail
Gmail
Connect appRules to a Gmail mailbox via the Gmail REST API. Supports reading messages and folders (labels), sending mail, creating drafts, moving/copying messages between labels, and the common message-level operations through the Email connector.
For Google Workspace accounts where OAuth is impractical, Gmail can also be reached via IMAP + SMTP using the Generic IMAP path with a Google App Password. See the IMAP page for that configuration.
Prerequisites
Before you can connect appRules to a Gmail mailbox, you need a Google Cloud project with the Gmail API enabled and an OAuth 2.0 client registered. The next section walks you through setting that up in the Google Cloud Console.
Step 1 — Create (or pick) a Google Cloud project
Open console.cloud.google.com.
In the top bar, click the project selector → New Project (or pick an existing one if you have one for this).
Give it a name (
appRules Emailis fine) and create it.
Step 2 — Enable the Gmail API
Left menu → APIs & Services → Library.
Search for
Gmail API→ click the result → click Enable.Wait a few seconds for the enablement to complete.
Step 3 — Configure the OAuth consent screen
This is the sign-in prompt your users see when they authorize the connector.
Left menu → APIs & Services → OAuth consent screen.
User Type:
Internal— if you're on Google Workspace and only users in your own Workspace organization will connect. No Google verification needed.External— if the mailbox is a personal Gmail account, or if users outside your Workspace will connect. Requires Google verification for production use of sensitive scopes (see note below).
Fill in the required fields:
App name:
appRules Email(shown to users on the sign-in screen).User support email: pick yours from the dropdown.
Developer contact information: your email.
Scopes page: click Add or Remove Scopes and add
https://mail.google.com/(full mailbox access — needed for read + sendmodify). For read-only use, add
https://www.googleapis.com/auth/gmail.readonlyinstead. Both are classed by Google as sensitive scopes, which matters for the publishing step below.
Test users page (External only): add every Gmail address that will authorize while the app is in "Testing" status. Without this, users outside the test list get an "access blocked" error.
Publishing status:
Testing — works, but refresh tokens expire after 7 days. Fine for development; painful in production because the connector will stop working weekly until re-authorized.
In production — refresh tokens don't expire. To move an app with sensitive scopes to production, Google requires app verification (video demo + security review). Internal Workspace apps skip this.
Step 4 — Create the OAuth 2.0 client
Left menu → APIs & Services → Credentials → + Create Credentials → OAuth client ID.
Application type:
Web application.Name:
appRules Email Client(shown only in the Cloud Console).Authorized redirect URIs: click + Add URI and enter
http://localhost:33333exactly as written (no trailing slash). This must match theCallback URLyou'll use in the connection string.Click Create. Google shows you the Client ID (ends in
.apps.googleusercontent.com) and the Client secret (starts withGOCSPX-).Copy both immediately — the secret can be retrieved later but it's easier to copy now.
Step 5 — Collect what you'll paste into the connection string
By the end of the Google setup you should have:
Client ID
OAuth Client Id
Client secret
OAuth Client Secret
Authorized redirect URI
Callback URL
You obtain the initial refresh token interactively via the OAuth Configuration window the first time you connect (next section). After that, access tokens are refreshed automatically — as long as the app is Published (not Testing), per Google's 7-day rule for Testing-mode tokens.
Connection parameters
Keywords are case-insensitive, and both spaced and unspaced forms are accepted (OAuth Client Id and OAuthClientId work the same).
Required — identifying the provider
Email Provider
Gmail
Selects the Gmail API backend.
Auth Scheme
OAuth or AccessToken
How to authenticate. OAuth uses a refresh token (recommended). AccessToken uses a short-lived bearer token (diagnostics only).
Required — OAuth with refresh token (Auth Scheme = OAuth)
OAuth Client Id
Client ID from Google Cloud Console (format: <id>.apps.googleusercontent.com).
OAuth Client Secret
Client secret from the same OAuth client credential.
OAuth Refresh Token
Refresh token obtained through the initial authorization flow.
Required — pre-obtained access token (Auth Scheme = AccessToken)
OAuth Access Token
A valid bearer token for the Gmail API. Short-lived (typically one hour).
Optional
Callback URL
http://localhost:33333
OAuth redirect URI; must match what's configured on your Google Cloud OAuth client.
OAuth Scopes
(empty → https://mail.google.com/)
Space-delimited scope list. Use a narrower scope like https://www.googleapis.com/auth/gmail.readonly for read-only access.
Timeout
60
HTTP timeout in seconds.
Logging
Log File
%APPDATA%\appStrategy\PortalData\Default\Logs\Connectors\Email_Debug.log
Path to the log file.
Log Level
0
0 off, 1 connection and statements, 2 one line per HTTP request, 3 also values and request bodies.
Log Max Size MB
100
Roll the log file at this size (0 = unlimited).
Log Compress
True
gzip closed log files in the background.
Log Max Line Length
16384
Truncate overlong lines (0 = unlimited).
Log Max Total MB
0
Total kept size of closed logs, oldest deleted first.
Log Retention Days
0
Delete closed logs older than N days.
Advanced — proxy, firewall, SSL
These configure the underlying HttpClient. Typically not needed for a direct Internet connection, but accepted when present.
Proxy Auto Detect
True
Honor the system proxy.
Proxy Server, Proxy Port
(empty), 80
Explicit HTTP proxy.
Proxy User, Proxy Password, Proxy Exceptions
(empty)
Proxy auth and bypass list.
Firewall Type
NONE
TUNNEL, SOCKS4, SOCKS5, or HTTP.
Firewall Server, Firewall Port, Firewall User, Firewall Password
(empty)
Firewall configuration.
SSL Server Cert
(empty)
* trusts any certificate; a PEM string, file path, or thumbprint pins that specific certificate.
Not applicable to Gmail
These parameters appear elsewhere in the Email connector but have no effect on Gmail connections and should be left out: Tenant Id, User Principal Name, API Version, Host, Port, Use SSL, SMTP Host, SMTP Port, SMTP Use SSL, Default Folder, Use POP3, POP3 Host, POP3 Port.
Example connection strings
Standard — OAuth with refresh token:
Read-only — narrower scope:
Diagnostic — pre-obtained access token:
Getting a refresh token (first-time setup)
The portal provides an OAuth Configuration window that runs the authorization flow and fills in the tokens for you. You do not need to call any stored procedure, start a listener, or copy URLs between windows yourself.
Open the connection's Configure Connection String window and fill in OAuth Client Id, OAuth Client Secret, and Callback URL (default:
http://localhost:33333). Set Auth Scheme toOAuth.Open the OAuth Configuration window from that dialog.
Authorization URL, Token Endpoint, Scopes, Prompt, and Access Type are prefilled from the built-in provider definition for Gmail.
Client Id, Client Secret, and Callback URL are prefilled from the connection string you just entered.
PKCE is prefilled from the provider default; override only if your Google OAuth client is configured for it.
Click Get Token. The portal starts a local HTTP listener on the callback URL, opens a popup to Google's sign-in page, and waits for the redirect. Sign in with the Google account whose mailbox you want to connect to and consent to the requested scopes.
The popup closes automatically once the authorization code arrives. The portal exchanges it for an access token and a refresh token, writes both back to the connection string (
OAuth Access Token,OAuth Refresh Token), and refreshes the Configure Connection String window.Save the connection. From that point on, access tokens are refreshed automatically — you do not need to open the OAuth Configuration window again unless the refresh token is revoked.
If Google does not return a refresh token (common for Google — the token is only issued on the very first authorization, and only when the request includes access_type=offline and prompt=consent), the form raises a message explaining how to re-authorize. Make sure Access Type is offline and Prompt is consent before clicking Get Token again.
Schema
A Gmail connection exposes three virtual tables:
Messages — most Graph-standard columns are mapped from Gmail's message resource. Gmail-specific columns
ThreadId,LabelIds, andSnippetare populated. Microsoft Graph-only columnsConversationId,Categories,Importance, andFlagStatusare not.Folders — Gmail labels, both system labels (
INBOX,SENT,TRASH,DRAFT,SPAM,STARRED,IMPORTANT,UNREAD,CATEGORY_*) and user-created labels. TheName,Type, andIdcolumns reflect Gmail's label structure.Attachments — attachments of a given message. Requires a
MessageIdfilter in the WHERE clause.
Supported operations
SELECTon Messages, Folders, AttachmentsINSERT INTO Messages— sends mail, or creates a draft whenIsDraft = trueINSERT INTO Folders— creates a user labelUPDATE Messages— mark as read/unread, add or remove labelsDELETE FROM Messages— moves the message to Trash (Gmail convention; not a hard delete)
Stored procedures: SendMail, Reply, ReplyAll, Forward, MarkAsRead, MarkAsUnread, MoveMessage (relabel), DownloadAttachment, ListFolders, GetUserInfo, SetLabels (Gmail-specific), GetOAuthAuthorizationUrl, GetOAuthAccessToken, RefreshOAuthAccessToken.
The three OAuth procedures are the low-level building blocks the OAuth Configuration window uses internally. For normal use, you don't call them yourself — use the window.
Troubleshooting
invalid_granton connection open — refresh token expired or revoked. Re-run the authorization flow to get a fresh one. Google revokes refresh tokens when the user changes their password, hasn't used the token for 6 months, or the Cloud project is still in "Testing" OAuth status (refresh tokens expire after 7 days in that mode).invalid_client— Client ID or Client Secret doesn't match a credential in your Google Cloud project.insufficient_scopeon a specific operation — the refresh token was issued for a narrower scope than the operation requires. Re-authorize withhttps://mail.google.com/or the specific scope needed.403 on SELECT from Messages — the Gmail API isn't enabled for the Cloud project, or the OAuth consent screen hasn't been configured for the required scopes.
Connection opens but no messages come back — check
Log Level=2and look at the Gmail query URL: if it includeslabelIds=INBOXbut you expected other labels, review your WHERE clause. Gmail uses label-based filtering, soWHERE ParentFolderId = 'SENT'is how you'd read Sent Mail.Pagination surprises on large folders — Gmail paginates with
pageTokenrather than$top/$skip. Very large SELECTs will take several round-trips; useLIMIT Nto cap.
Last updated