Allowing Integrate.io ETL access to 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 Gmail connection in Integrate.io ETL.

A) Set Up the Gmail (Gmail) Service Account Connection:
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 Gmail Connection on Integrate.io ETL

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

B) Gmail OAuth Connection:

  Steps : Create Gmail (OAuth) Connection on Integrate.io ETL

1. Navigate to the Connections tab and click + New connection.
2. Search for and select Gmail (OAuth).
3. Click Authenticate.
4. A Google sign-in popup will appear. Select the Google account you want to connect.
5. Review the requested permissions:
6. Once authentication completes, fill in the Connection Name (e.g. My Gmail OAuth).
7. Click Test Connection to verify, then click Create Connection.

Token Refresh:

Using the Connection in Dataflows:

1.  Add a Gmail (Gmail) source component to your dataflow
2. In the connection dropdown, select your Gmail OAuth connection (both Service Account and OAuth connections appear in the same dropdown)
3. Configure the Gmail search query, filename pattern, and CSV settings as usual

Revoking Access

  Alternatively, delete the connection from Integrate.io's Connections page -- this also invalidates the refresh token.