Allowing Integrate.io ETL access to Google Mail (Gmail)

Integrate.io ETL can read CSV file attachments from your Gmail inbox and ingest them into your ETL pipelines. This article details how to set up the Google Mail (Gmail) connection in Integrate.io ETL.

This connector uses a Google Service Account with domain-wide delegation for authentication.

Step 1: Create a GCP Project

1. Access your Google Cloud Console.
2. Click the project dropdown at the top of the page and select existing project or create a New Project.
3. If a new project is created, enter a project name (e.g. my-gmail-connector) and click Create. Make sure the newly created project is selected in the project dropdown before proceeding.

Step 2: Enable the Gmail API

1. In the left sidebar, navigate to APIs & Services → Library.
2. Search for Gmail API.
3. Click the Gmail API result and click Enable.

Step 3: Create a Service Account

1. In the left sidebar, navigate to IAM & Admin → Service Accounts.
3. Click + Create Service Account.
4. Fill in the service account details:
   • Name: e.g. gmail-connector-reader
   • Description: e.g. Service account for Integrate.io Gmail CSV connector
5. Click Create and Continue.
6. Skip the optional role grant steps — Gmail access is controlled via domain-wide delegation, not IAM roles.
7. Click Done.

Step 4: Enable Domain-Wide Delegation

1. From the Service Accounts list, click the service account you just created.
2. Go to the Details tab.
3. Scroll down to Advanced settings and find the Domain-wide Delegation section.
4. Click Enable Google Workspace Domain-wide Delegation.
5. Enter a product name (e.g. Integrate.io Gmail Connector) and click Save.
6. Note the Client ID displayed — this is the long numeric ID (e.g. 118304762983475829341) you will need in Step 6.

💡 Finding the Client ID: The Client ID is also available inside the JSON key file downloaded in Step 5, under the client_id field.

Step 5: Download the JSON Key

1. Still on the service account page, go to the Keys tab.
2. Click Add Key → Create new key.
3. Select JSON and click Create.
4. A .json key file will be automatically downloaded to your machine. Keep this file secure — it contains the private key used to authenticate the service account.

The JSON file will contain a structure similar to:

{
  "type": "service_account",
  "project_id": "your-project",
  "private_key_id": "...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\\n...",
  "client_email": "gmail-connector-reader@your-project.iam.gserviceaccount.com",
  "client_id": "118304762983475829341",
  ...
}

This is the file you will upload to Integrate.io in Step 7.

Step 6: Authorize the Scope in Google Workspace Admin

⚠️ This step requires Google Workspace Admin access to the organization whose Gmail you want to connect. If you are setting this up for a client, this step must be completed by their Workspace administrator.

1. Go to admin.google.com and sign in as a Workspace admin.
2. Navigate to Security → Access and data control → API controls.
3. Click Manage Domain-Wide Delegation.
4. Click Add new.
5. Enter the following:
   • Client ID: The numeric Client ID from Step 4 (e.g. 118304762983475829341)
   • OAuth scopes: https://www.googleapis.com/auth/gmail.readonly
6. Click Authorize.

This authorizes the service account to impersonate users in the domain and access their Gmail data on behalf of Integrate.io.

Step 7: Create Google Mail (Gmail) Connection on Integrate.io ETL

1. Navigate to the Connections tab and click Google Mail (Gmail).
2. Fill up the Connection Name
3. Upload the JSON key you generated from Step 1.
4. Click Test Connection and Create Connection