Skip to main content

​
Pre-Built Tooling

CategoryDetails
AuthenticationOAuth 2.0 (Authorization Code with refresh tokens)
Two-Way SyncNo
Events SupportedNo
RealtimePolling
Supports Rate LimitingYes (Google API quotas & 429 handling)
Authentication Scopes Supportedhttps://mail.google.com/ (full access), https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.send, https://www.googleapis.com/auth/gmail.compose, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.labels, https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile

​
Objects Supported

Alloy Automation supports syncing the following objects from Gmail:
  • Drafts
  • Labels
  • Messages
  • Threads
  • Profile
  • Attachments

​
Set Up Guide

​
Trial Access

QuestionAnswer
Offers free trial?Yes. Create a free Google account at https://accounts.google.com/signup and set up a Google Cloud project at https://console.cloud.google.com.
Requires paid sandboxNo paid sandbox required.
Requires partnership to obtain authentication?No. However, Google App Verification may be required in production for sensitive scopes, which can add review time.

​
Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation’s.

​
Create your OAuth app (Google Cloud Console)

  1. Go to Google Cloud Console (https://console.cloud.google.com) → APIs & Services → Credentials.
  2. Create an OAuth client ID (application type: Web application).
  3. Add the redirect URI: https://api.runalloy.com/api/strategy/connector/gmail/callback
  4. Enable the Gmail API for your project (APIs & Services → Library).
  5. Configure the scopes you intend to request:
    • https://mail.google.com/ (full access)
    • https://www.googleapis.com/auth/gmail.readonly (read-only access)
    • https://www.googleapis.com/auth/gmail.send (send emails)
    • https://www.googleapis.com/auth/gmail.compose (compose and send)
    • https://www.googleapis.com/auth/gmail.modify (read, compose, send)
    • https://www.googleapis.com/auth/gmail.labels (manage labels)
    • https://www.googleapis.com/auth/userinfo.email
    • https://www.googleapis.com/auth/userinfo.profile
  6. Copy your Client ID and Client Secret into Alloy Automation.
  • Set up the OAuth consent screen with your app details and domain.
  • For production use or external users, complete Google app verification (may require demo video, privacy policy, and domain ownership).
  • If using the full https://mail.google.com/ scope, expect stricter review requirements.

​
Use Cases

​
1) Automated email management and routing

Monitor incoming emails matching specific criteria (labels, senders, keywords) and automatically route them to appropriate systems, create tasks, or trigger workflows based on email content.

​
2) Email-to-ticket automation

Automatically parse incoming Gmail messages and create support tickets, CRM leads, or project tasks in your application, including attachment handling and thread tracking.

​
3) Scheduled email campaigns and drip sequences

Build automated email sequences that send personalized messages based on user actions, signup dates, or custom triggers while maintaining thread continuity and tracking responses.

​
4) Gmail inbox integration for SaaS apps

Embed Gmail functionality directly into your application, allowing users to send, receive, and manage emails without leaving your platform, with full label and search capabilities.

​
5) Email data extraction and analysis

Extract email content, metadata, and attachment data for analytics, compliance archiving, or machine learning pipelines, with support for filtering by date ranges, labels, and search queries.

​
API Gotchas

  • ⚠️ Partial responses & fields selection: Gmail’s API often benefits from specifying the format parameter and metadataHeaders to limit payload size. Fetching full message bodies repeatedly can hit quota limits quickly. Use format=metadata or format=minimal when you don’t need full content.
  • ⚠️ Base64URL encoding for message bodies: When sending or creating messages with the raw field, Gmail expects the entire MIME message to be base64url encoded (not standard base64). Missing this encoding causes 400 errors.
  • ⚠️ Label IDs vs Label names: Gmail uses label IDs (e.g., Label_123) internally, but also has system labels with special IDs like INBOX, SENT, DRAFT, SPAM, and TRASH. Always use the listLabels endpoint to map user-facing names to IDs.
  • ⚠️ Query syntax differences: Gmail search queries (the q parameter) use Gmail’s search operators (like from:, to:, subject:, is:unread, has:attachment), not standard SQL or REST filtering. Test queries in the Gmail web interface first.
  • ⚠️ History API limitations: Gmail’s history API requires storing the historyId from previous requests to detect changes. If you lose this ID or it expires, you must perform a full sync again.
  • ⚠️ App verification (production): Using broad scopes like https://mail.google.com/ triggers a stricter Google review process that can take weeks. If you only need limited access, prefer narrower scopes (e.g., gmail.send or gmail.readonly) to ease verification.
For questions or troubleshooting, contact support@runalloy.com.
⌘I