Skip to main content
Gmail Logo

​
Gmail

Email management and communication

✅ Ready📖 Documentation Available

​
Configuration Guide

​
Overview

The Gmail connector allows you to access, manage, and synchronize email data from Gmail, including attachments and embedded documents.Gmail is Google’s email service that provides access to emails, attachments, and related content. This connector enables synchronization of Gmail data including emails and their associated documents (Google Docs, Sheets, and Slides).

​
Authentication

The Gmail connector uses OAuth 2.0 for authentication. This requires users to grant permission for the application to access their Gmail data within the scopes specified.

​
How to configure and enable the Gmail Connector

​
Step 1: Create a Google Cloud Project & Set Up Admin Access

  1. Sign in as Super Administrator:
    Log in to the Google Cloud Console using an account with super administrator privileges.
  2. Create a New Project:
    • Click on the project dropdown at the top of the console and select New Project
    • Enter a project name and (optionally) assign it to a folder or organization
    • Click Create
Create Google Cloud Project
Only the project creator has full control by default. It is recommended to add at least one additional administrator (using the IAM settings) to ensure continued access even if the original creator leaves your organization.

​
Step 2: Enable Required APIs

  1. Navigate to APIs & Services > Library in the Cloud Console
  2. Search for and enable the following APIs required for Gmail sync:
    • Gmail API (required for email access)
    • Google Docs API (required for Google Docs attachments)
    • Google Sheets API (required for Google Sheets attachments)
    • Google Slides API (required for Google Slides attachments)
    • Admin SDK API (required for domain-wide delegation)
Enabled Google APIs in Google Cloud Console
Make sure that all of the listed APIs are enabled to ensure smooth operation of the Gmail connector.

​
Step 3: Create a Service Account

  1. Navigate to IAM & Admin > Service Accounts in the Cloud Console
  2. Click Create Service Account
Create Service Account
  1. Enter a Service Account Name and an optional Description
  2. Click Create and Continue, then Done
Create Service Account
  1. Copy the Unique ID for use in the next step
Copy Service Account ID

​
Step 4: Delegate Domain-Wide Authority

  1. Sign in to the Google Admin Console with a super administrator account
  2. Navigate to Security > Access and data control > API controls
  3. Click Manage Domain Wide Delegation
  4. Click Add new and paste the service account’s client ID
  5. Add the following OAuth scopes required for Gmail sync:
https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/presentations.readonly
These scopes are required for Gmail synchronization:
  • gmail.readonly: Access to read Gmail messages
  • documents.readonly: Access to Google Docs files attached to emails
  • spreadsheets.readonly: Access to Google Sheets files attached to emails
  • presentations.readonly: Access to Google Slides files attached to emails
  • Admin scopes: Required for domain-wide delegation
  1. Click Authorize
Domain-wide delegation lets your service account impersonate users within your domain. Make sure that both the service account and the end user email belong to the same domain.

​
Step 5: Create a JSON Key for the Service Account

  1. In the Service Accounts list, select your newly created service account
  2. Click on the Keys tab
  3. Click Add Key and select Create new key
  4. Choose JSON as the key type and click Create
  5. Save the automatically downloaded JSON key file
Store this JSON file securely as it contains sensitive credentials and cannot be recovered if lost.
It might be that while creating the key you get the error:
Organization Policy Error
In this case, follow the steps given under the heading Enable Service Account Key Creation.
If your key was successfully created and downloaded, you can use that key in the enterprise search application.

​
Configuring and enabling connector

  1. Navigate to the Connectors page in your account settings:
    • Go to Account > Company Settings > Settings > Connectors
Empty connector list
  1. Click on “Add New Connectors” or “Browse Available Connectors” view available connectors
Connector registry
  1. Find and click on the Gmail connector card to create a new connector instance
  2. In the configuration dialog that opens:
    • Enter an Instance Name for your connector (e.g., “Company Gmail”)
    • Enter the Admin Email (Admin user’s email with which you created the Google Cloud credentials)
    • Select the JSON key file to upload
    • Click on Save button to save the configuration
Configure Gmail connector
  1. After saving, you will be redirected to the connector instance page. To enable the connector:
    • Use the Sync toggle switch to enable data synchronization
    • The connector will start syncing Gmail data once enabled
Gmail connector sync status

​
Enable Service Account Key Creation

If you encounter an error while creating the service account key due to organization policy constraints, follow these steps:

​
1. Switch to the Organization Context

At the top of the Google Cloud Console (where the project name is shown), click the drop-down to see a list of organizations and projects.Select your organization rather than a specific project.If you don’t see an organization listed, make sure you’re signed in with an account that has access to the organization.

​
2. Add Organisation Policy Administrator Role

Navigate to IAM & Admin > IAM in the Cloud ConsoleFind the current user and Click on the Pencil icon.Click on the Add another role button.Search for the Organisation Policy Administrator role.Click on the Add button.
Add Organisation Policy Administrator
Click on the Save button.

​
3. Disable the Service Account Key Creation constraint

Navigate to IAM & Admin > Organization Policies in the Cloud ConsoleSearch for "iam.disableServiceAccountKeyCreation"Select the policyClick on the Manage Policy buttonIn Policy source, Select Override parent’s policy. Add a rule and set the enforcement to “Off”Click on the Save buttonAfter completing these steps, return to Step 5 and try creating the service account key again.

​
Google PubSub Configuration

PubSub setup enables real-time updates for Gmail content. While optional, it’s highly recommended for maintaining up-to-date content in Enterprise search.

​
Step 1: Set Up a Cloud Pub/Sub Topic

  1. Navigate to Pub/Sub > Topics in the Cloud Console sidebar
  2. Click Create Topic
  3. Enter a unique name (e.g., projects/your-project-id/topics/gmail-webhook-topic)
  4. Check “Add a default subscription”
  5. Click Create to confirm
Create Topic

​
Step 2: Configure the Subscription

  1. Go to Pub/Sub > Topics
  2. Select the subscription created with the topic
  3. Click Edit
  4. Change Delivery type to “Push”
  5. Set Endpoint URL as “your_base_url/gmail/webhook”
  6. Adjust Expiry Period as needed
  7. Click Update
Ensure your base URL matches the Enterprise search connector service base URL

​
Step 3: Set Topic Permissions

  1. In Pub/Sub > Topics, select your topic
  2. Open the Info Panel (right side)
  3. Click Add Principals
  4. Add [email protected]
  5. Assign the Pub/Sub Publisher role
Add Principals
  1. Click Save
If you encounter an organizational policy constraint error, modify the policy in organizational policies to allow the given domain. Allow 5-10 minutes for changes to propagate.

​
Overview

The Gmail connector allows you to access, manage, and synchronize email data from Gmail, including attachments and embedded documents.Gmail is Google’s email service that provides access to emails, attachments, and related content. This connector enables synchronization of Gmail data including emails and their associated documents (Google Docs, Sheets, and Slides).

​
Authentication

The Gmail connector uses OAuth 2.0 for authentication. This requires users to grant permission for the application to access their Gmail data within the scopes specified.

​
Step 1: Create a Google Cloud Project

  1. Access the Google Cloud Console
  2. Create a project (if you don’t have one)
  3. Note your project ID for later use

​
Step 2: Enable Required APIs

  1. Navigate to APIs & Services > Library in the Cloud Console
  2. Search for and enable the following APIs required for Gmail sync:
    • Gmail API (required for email access)
    • Google Docs API (required for Google Docs attachments)
    • Google Sheets API (required for Google Sheets attachments)
    • Google Slides API (required for Google Slides attachments)
Enabled Google APIs in Google Cloud Console
Make sure that all of the listed APIs are enabled to ensure smooth operation of the Gmail connector.
  1. Navigate to APIs & Services > OAuth consent screen in the Cloud Console
  2. Configure the OAuth consent screen with your application details
  3. Add the required scopes (see Step 5)

​
Step 4: Create OAuth Client ID

  1. Navigate to APIs & Services > Credentials in the Cloud Console
  2. Click Create Credentials and select OAuth client ID
  3. Select Web application as the application type
  4. Set the Authorized redirect URI to: 
    http://your-frontend-dns/connectors/oauth/callback/Gmail
    or for HTTPS: 
    https://your-frontend-dns/connectors/oauth/callback/Gmail
  5. Click Create and note your Client ID and Client Secret
Redirect URI must match exactly your frontend URL. For example: if your app is running on https://f7f0-240.ngrok-free.app then redirect URI should be https://f7f0-240.ngrok-free.app/connectors/oauth/callback/Gmail in Google Cloud Console.

​
Step 5: Configure OAuth Scopes

  1. In the OAuth consent screen, navigate to the Scopes section
  2. Add the following OAuth scopes required for Gmail sync:
    • https://www.googleapis.com/auth/gmail.readonly - Read Gmail messages
    • https://www.googleapis.com/auth/documents.readonly - Read Google Docs files
    • https://www.googleapis.com/auth/spreadsheets.readonly - Read Google Sheets files
    • https://www.googleapis.com/auth/presentations.readonly - Read Google Slides files
These scopes allow the connector to:
  • Access and read Gmail messages
  • Access Google Docs, Sheets, and Slides files that are attached to or embedded in emails

​
Configuring and enabling connector

  1. Navigate to the Connectors page in your account settings:
    • Go to Account > Individual Settings > Settings > Connectors
Empty connector list
  1. Click on “Add New Connectors” or “Browse Available Connectors” view available connectors
Connector registry
  1. Find and click on the Gmail connector card to create a new connector instance
  2. In the configuration dialog that opens:
    • Enter an Instance Name for your connector (e.g., “My Gmail”)
    • Enter the Google Client ID from your Google Cloud Console
    • Enter the Google Client Secret from your Google Cloud Console
    • Click on Save button to save the configuration
      Gmail auth configuration
  3. After saving, you will be redirected to the connector instance page. To enable the connector:
Gmail connector before authentication
  • Click on the Authenticate button (or use the Sync toggle switch)
  • You will be redirected to Google’s consent screen where you need to sign in and grant permission for Gmail and related document access
Google consent screen for Gmail connector
  1. After giving consent, it will redirect to the frontend and if the Google Workspace shows enabled, then your connector is successfully configured and enabled.
    Gmail connector sync status
Give consent with the same email as used for email in PipesHub.
For setting up Google PubSub notifications, please refer to the Google PubSub Configuration Guide in the Enterprise documentation.

​
Ready to Get Started?

The Gmail connector is fully operational and ready for use. Follow the configuration guide above for your setup type (Enterprise or Individual), or reach out to our support team if you need assistance.