## 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](https://console.cloud.google.com/) 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**
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)
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**
3. Enter a **Service Account Name** and an optional **Description**
4. Click **Create and Continue**, then **Done**
5. Copy the **Unique ID** for use in the next step
### Step 4: Delegate Domain-Wide Authority
1. Sign in to the [Google Admin Console](https://admin.google.com/) 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
6. 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:
In this case, follow the steps given under the heading [Enable Service Account Key Creation](#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 **Workspace Settings** > Under **Workspace** section in sidebar > **Connectors** in your application.
2. Search for the **Gmail** connector and click on **Setup** to configure a connector instance.
3. 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 the **Next** button to save the configuration and move to configure connector settings page. You can learn about the connector settings in the [Connector Settings](/connectors/google-workspace/gmail/gmail#connector-settings) section.
4. After configuring connector settings, you can click on **Save Configuration**.
Once PipesHub confirms the instance is ready, you can choose either **Start syncing now** or select the **I'll do it later** option.
{" "}
### 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 Console
Find 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.
Click on the **Save** button.
#### 3. Disable the Service Account Key Creation constraint
Navigate to **IAM & Admin > Organization Policies** in the Cloud Console
Search for `"iam.disableServiceAccountKeyCreation"`
Select the policy
Click on the **Manage Policy** button
In Policy source, Select **Override parent's policy**. Add a rule and set the enforcement to "Off"
Click on the **Save** button
After completing these steps, return to [Step 5](#step-5%3A-create-a-json-key-for-the-service-account) 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
### 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 `gmail-api-push@system.gserviceaccount.com`
5. Assign the **Pub/Sub Publisher** role
6. 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.
