> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ETL: Connecting to Gmail

> Authorize Integrate.io ETL to access your Gmail account using OAuth and extract email metadata and contents into your data pipelines for analysis.

[Integrate.io](http://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](http://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

<Steps>
  <Step>
    Access your [Google Cloud Console](https://console.cloud.google.com/).
  </Step>

  <Step>
    Click the project dropdown at the top of the page and select existing project or create a **New Project**.
  </Step>

  <Step>
    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.

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-1.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=9b2e6f9319aa65b908478e06339dde3b" alt="Creating a new project in Google Cloud Console" width="1200" height="704" data-path="images/connectivity-and-security/google-mail-gmail/image-1.webp" />
    </Frame>
  </Step>
</Steps>

## Step 2: Enable the Gmail API

<Steps>
  <Step>
    In the left sidebar, navigate to **APIs & Services → Library**.
  </Step>

  <Step>
    Search for **Gmail API**.
  </Step>

  <Step>
    Click the Gmail API result and click **Enable**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-2.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=acb1905f710e456b07e55a79a0d6d5dd" alt="Enabling the Gmail API in Google Cloud Console" width="1200" height="603" data-path="images/connectivity-and-security/google-mail-gmail/image-2.webp" />
    </Frame>
  </Step>
</Steps>

## Step 3: Create a Service Account

<Steps>
  <Step>
    In the left sidebar, navigate to **IAM & Admin → Service Accounts**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-3.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=e18e17d8f411d43c24d698e6ef1bd151" alt="Creating a service account in Google Cloud Console" width="1200" height="766" data-path="images/connectivity-and-security/google-mail-gmail/image-3.webp" />
    </Frame>
  </Step>

  <Step>
    Click **+ Create Service Account**.
  </Step>

  <Step>
    Fill in the service account details:

    * **Name**: e.g. `gmail-connector-reader`
    * **Description**: e.g. `Service account for Integrate.io Gmail CSV connector`
  </Step>

  <Step>
    Click **Create and Continue**.
  </Step>

  <Step>
    Skip the optional role grant steps. Gmail access is controlled via domain-wide delegation, not IAM roles.
  </Step>

  <Step>
    Click **Done**.
  </Step>
</Steps>

## Step 4: Enable Domain-Wide Delegation

<Steps>
  <Step>
    From the **Service Accounts** list, click the service account you just created.
  </Step>

  <Step>
    Go to the **Details** tab.
  </Step>

  <Step>
    Scroll down to **Advanced settings** and find the **Domain-wide Delegation** section.
  </Step>

  <Step>
    Click **Enable Google Workspace Domain-wide Delegation**.
  </Step>

  <Step>
    Enter a product name (e.g. `Integrate.io Gmail Connector`) and click **Save**.
  </Step>

  <Step>
    Note the **Client ID** displayed. This is the long numeric ID (e.g. `118304762983475829341`) you will need in Step 6.

    <Tip>**Finding the Client ID**: The Client ID is also available inside the JSON key file downloaded in Step 5, under the `client_id` field.</Tip>
  </Step>
</Steps>

## Step 5: Download the JSON Key

<Steps>
  <Step>
    Still on the service account page, go to the **Keys** tab.
  </Step>

  <Step>
    Click **Add Key → Create new key**.
  </Step>

  <Step>
    Select **JSON** and click **Create**.
  </Step>

  <Step>
    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.
  </Step>
</Steps>

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](http://integrate.io/) in Step 7.

## Step 6: Authorize the Scope in Google Workspace Admin

<Warning>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.</Warning>

<Steps>
  <Step>
    Go to [admin.google.com](http://admin.google.com/) and sign in as a Workspace admin.
  </Step>

  <Step>
    Navigate to **Security → Access and data control → API controls**.
  </Step>

  <Step>
    Click **Manage Domain-Wide Delegation**.
  </Step>

  <Step>
    Click **Add new**.
  </Step>

  <Step>
    Enter the following:

    * **Client ID**: The numeric Client ID from Step 4 (e.g. `118304762983475829341`)
    * **OAuth scopes**: `https://www.googleapis.com/auth/gmail.readonly`
  </Step>

  <Step>
    Click **Authorize**.

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-4.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=ecac667cfda21e1b90670e41e163f147" alt="Authorizing API scopes in Google Workspace Admin" width="1200" height="416" data-path="images/connectivity-and-security/google-mail-gmail/image-4.webp" />
    </Frame>
  </Step>
</Steps>

This authorizes the service account to impersonate users in the domain and access their Gmail data on behalf of [Integrate.io](http://integrate.io/).

## Step 7: Create Gmail Connection on Integrate.io ETL

<Steps>
  <Step>
    Navigate to the **Connections** tab and click **Gmail.**

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-5.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=68807011c2cafebedffd3497196267c5" alt="Selecting Gmail from the connections list" width="1200" height="829" data-path="images/connectivity-and-security/google-mail-gmail/image-5.webp" />
    </Frame>

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-6.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=63baf298f077f7022aa03d3d9d5e38b8" alt="Gmail connection configuration form" width="1200" height="595" data-path="images/connectivity-and-security/google-mail-gmail/image-6.webp" />
    </Frame>
  </Step>

  <Step>
    Fill up the Connection Name
  </Step>

  <Step>
    Upload the JSON key you generated from Step 1.
  </Step>

  <Step>
    Click **Test Connection** and **Create Connection**

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-7.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=d93f7cd0301886f8e0ff65d3d9156a1d" alt="Uploading the JSON key file for Gmail connection" width="1200" height="1035" data-path="images/connectivity-and-security/google-mail-gmail/image-7.webp" />
    </Frame>
  </Step>
</Steps>

## B) Gmail OAuth Connection:

As an alternative to Service Account authentication, Integrate.io ETL also supports connecting to Gmail via OAuth 2.0. This is the recommended method when you don't have Google Workspace Admin access or want to connect a personal Gmail account.

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

<Steps>
  <Step>
    Navigate to the Connections tab and click + New connection.
  </Step>

  <Step>
    Search for and select **Gmail (OAuth)**.
  </Step>

  <Step>
    Click Authenticate.
  </Step>

  <Step>
    A Google sign-in popup will appear. Select the Google account you want to connect.
  </Step>

  <Step>
    Review the requested permissions:
  </Step>

  <Step>
    Once authentication completes, fill in the Connection Name (e.g. My Gmail OAuth).
  </Step>

  <Step>
    Click Test Connection to verify, then click Create Connection.

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-8.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=45caef05471320605e75e621b3598b40" alt="Gmail OAuth connection setup in Integrate.io" width="1200" height="600" data-path="images/connectivity-and-security/google-mail-gmail/image-8.webp" />
    </Frame>

    <Frame>
      <img src="https://mintcdn.com/integrateio/EbCNa5DlFLu_U6wb/images/connectivity-and-security/google-mail-gmail/image-9.webp?fit=max&auto=format&n=EbCNa5DlFLu_U6wb&q=85&s=b1b94735dbefc0c974403f38a4ba7cae" alt="Gmail OAuth connection completed" width="1200" height="597" data-path="images/connectivity-and-security/google-mail-gmail/image-9.webp" />
    </Frame>
  </Step>
</Steps>

## Token Refresh:

Once created, the connection is automatically maintained:

* Access tokens are refreshed every 30 minutes in the background
* If a token expires during a job run, it is automatically renewed using the stored refresh token
* Use Test Connection on the connection detail page to manually verify the token is still valid

## Using the Connection in Dataflows:

The Gmail OAuth connection works with the same Gmail source component as the Service Account version. In the package designer

<Steps>
  <Step>
    Add a Gmail (Gmail) source component to your dataflow
  </Step>

  <Step>
    In the connection dropdown, select your Gmail OAuth connection (both Service Account and OAuth connections appear in the same dropdown)
  </Step>

  <Step>
    Configure the Gmail search query, filename pattern, and CSV settings as usual
  </Step>
</Steps>

## Revoking Access

To revoke Integrate.io's access to your Gmail:

<Steps>
  <Step>
    Visit Google Account Permissions
  </Step>

  <Step>
    Find Integrate.io in the list and click Remove Access
  </Step>
</Steps>

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