Skip to main content

Gmail Data Connector

Learn how to automatically ingest Google Workspace email into Torq to enable Auto Triage and trigger response workflows for email-borne threats.

Overview

The Gmail data connector continuously ingests email from your Google Workspace environment into Torq, routing structured email events to Auto Triage and workflows. Each email is parsed into an analysis-ready event (internet message headers, SPF/DKIM/DMARC verdicts, body content, extracted URLs, hyperlinks with anchor text, and attachment metadata) with no custom parsing required.

Key benefits

The Gmail data connector handles ingestion, parsing, and deduplication out of the box, so your team can focus on response rather than pipeline maintenance.

  • Simplified setup: Configure ingestion through a guided UI, no Pub/Sub infrastructure, custom polling logic, or per-mailbox trigger setup required.

  • Continuous polling: Mailboxes are polled every minute, ensuring a steady flow of email events into Torq.

  • Structured event output: Every email becomes a consistent JSON event with all security-relevant fields pre-parsed and ready for Auto Triage.

  • Broad mailbox support: Individual mailboxes and Gmail Collaborative Inboxes backed by a user identity are supported using the same configuration.

  • Built-in resilience: Transient errors and duplicate events are handled automatically.

Event throughput

The Gmail data connector supports up to 1500 incoming events per minute per Torq account. If this limit is exceeded, events are automatically queued and retried to ensure no data is lost.

Common scenarios

Triage org-wide inbound email automatically

All inbound email across your Google Workspace organization flows into Torq via the connector. Auto Triage receives each email as a structured event and automatically assesses sender reputation, authentication failures, suspicious URLs, and malicious attachment hashes, classifying, escalating, or remediating at scale. Analysts only review what Auto Triage surfaces.

Detect phishing campaigns across the organization

Because the connector ingests email from all configured mailboxes, Auto Triage can correlate signals in real time. When the same malicious URL or attachment hash appears across multiple inboxes simultaneously, Auto Triage identifies the coordinated campaign and triggers bulk response (quarantine, block, and notify) before it spreads.

Detect BEC and impersonation at ingestion time

Every email event includes parsed authentication headers, Reply-To, Return-Path, and SPF/DKIM/DMARC verdicts, alongside sender display name and address. Auto Triage consumes these fields to detect executive or vendor impersonation at the point of ingestion, with no additional enrichment calls required.

Prerequisites

Before setting up the Gmail data connector, ensure the following:

  • Google Workspace with Gmail enabled for target users.

  • Google Workspace admin access to enable domain-wide delegation and grant OAuth scopes to the service account.

  • Google Cloud project with the Gmail API and Admin SDK API enabled.

  • A Google Cloud service account with domain-wide delegation enabled and a downloadable JSON key.

  • Target mailboxes must exist in the organization before the connector is created. Individual mailboxes and Gmail Collaborative Inboxes backed by a user identity are supported.

  • Delegated admin email: Must be a Workspace admin (Super Admin or User Management Admin role) who can read the directory. This account is used during the health check to validate users via the Admin SDK.

How to use

Create a service account and enable domain-wide delegation

The connector authenticates using OAuth 2.0 with a Google Cloud service account and domain-wide delegation (DWD). A Workspace admin grants the service account permission to read mail on behalf of users in the domain. Complete both the Google Cloud and Google Workspace Admin Console steps below.

Create or select a Google Cloud project

  1. Go to the Google Cloud Console: Navigate to console.cloud.google.com.

  2. Select a project: Create a new project or select an existing one.

Enable required APIs

  1. Go to the API Library: Navigate to APIs & Services > Library.

  2. Enable the following APIs:

    • Gmail API

    • Admin SDK API

Create a service account and download the JSON key

  1. Go to Service Accounts: Navigate to IAM & Admin > Service Accounts and click Create Service Account.

  2. Name the account: Enter a unique and meaningful name (e.g., Torq Gmail Connector) and click Create and Continue.

  3. Skip optional roles: Click Done.

  4. Create a JSON key: Open the newly created service account, go to the Keys tab, and select Add Key > Create new key > JSON.

  5. Download and store the key: Save the JSON key file securely, this is your Service Account JSON. Treat it like a password and rotate it if required.

Note the service account client ID

  • Copy the Unique ID: On the service account details page, copy the Unique ID (also called the Client ID). You will need this when configuring domain-wide delegation.

Enable domain-wide delegation in Google Workspace

  1. Go to the Admin Console: Navigate to admin.google.com.

  2. Open API controls: Go to Security > Access and data control > API controls > Domain-wide delegation.

  3. Add a new entry: Click Add new.

  4. Enter the client ID: Paste the service account Unique ID from the previous step.

  5. Add OAuth scopes: Enter the scopes listed in the table below, comma-separated.

  6. Authorize: Click Authorize.

Scope

Purpose

https://www.googleapis.com/auth/gmail.readonly

Read email messages, attachments, and headers from configured mailboxes

https://www.googleapis.com/auth/gmail.metadata

View email message metadata such as labels and headers

https://www.googleapis.com/auth/admin.directory.user.
​readonly

Validate that configured mailbox addresses exist in the organization (health check only)

All three scopes are required. If any scope is missing, the connector health check fails with an authorization error.

Set up a data connector instance in Torq

  1. Open connector setup: Go to Build > Integrations > Triggers > Gmail Data Connector and click Add Instance.

  2. Configure connection details:

    • Instance name: Enter a unique and meaningful name (e.g., Contoso-Gmail-SOC).

    • Service account JSON: Upload the JSON key file downloaded in the previous step.

    • Delegated admin email: Enter the Workspace admin email the service account impersonates during the health check (e.g., admin@contoso.com). Must belong to the same domain that granted domain-wide delegation.

  3. Add mailboxes: Enter up to 10 Workspace mailbox email addresses, comma-separated. Gmail Collaborative Inboxes backed by a user identity are also supported.

  4. Add labels: Enter up to 10 Gmail label names, comma-separated. Inbox is pre-filled by default; you can add up to 9 additional labels. Supports system labels (SPAM, IMPORTANT, STARRED, CATEGORY_PERSONAL) and custom labels (e.g., Reported Phishing).

  5. Select routing destination: Choose where ingested events will be sent:

    • Workflows

    • Auto Triage

  6. Save: Click Add to create the connector. Ingestion starts automatically.

Ingestion starts from the moment the connector is created. There is no backfill; historical emails are not ingested.

Troubleshooting

"Proceed without Inbox label?" dialog appears on save

Inbox is not included in your labels list.

  1. Go back: Click Back to return to the form and add Inbox.

  2. Proceed anyway: Click Proceed to save without it, only the remaining resolved labels will be polled.

"We couldn't resolve folders [label names] for all users" dialog appears on save

One or more label names could not be matched, likely due to a typo or a label that doesn't exist in the mailbox. Label names are matched case-insensitively.

  1. Go back: Click Back to return to the form and correct the label names.

  2. Proceed anyway: Click Proceed to save with only the successfully resolved labels. Unresolved labels will not be polled.

Both dialogs are warnings, not hard blocks. The connector is created successfully either way.

FAQs

Are shared mailboxes supported?

Yes. Provide the Gmail Collaborative Inbox email address in the Users field, as long as the mailbox is backed by a user identity in Google Workspace. Standard Google Groups distribution lists without a user-backed inbox are not supported.

What happens if a monitored label is deleted after setup?

The connector logs a warning and skips that label for the current cycle. Other labels and mailboxes continue polling normally.

How is duplicate ingestion prevented?

Each message's Gmail message ID is stored per mailbox and label. Messages already processed are silently skipped.

What happens if the Gmail API rate limit is hit?

The connector handles rate limit responses automatically and retries on the next polling cycle. No data is lost.

Does updating the connector lose polling progress?

No. Polling state is persisted per mailbox × label combination and is preserved when you update the connector.

Related Articles
Did this answer your question?