> ## 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: Gmail Source
> Configure the Gmail source component in Integrate.io ETL to read CSV or Excel attachments and email body content from a Gmail inbox into your pipelines.
Use the Google Mail (Gmail) source component to read CSV or Excel file attachments, or the email body itself, from a Gmail inbox and ingest them into your [Integrate.io](http://integrate.io/) ETL pipeline.
## Connection Setup
Integrate.io ETL supports two authentication methods for Gmail: a Google **Service Account** with domain-wide delegation, or **OAuth 2.0**. Use OAuth when you don't have Google Workspace Admin access or want to connect a personal Gmail account.
### Service Account (domain-wide delegation)
#### Step 1: Create a GCP Project
Access your [Google Cloud Console](https://console.cloud.google.com/).
Click the project dropdown at the top of the page and select existing project or create a **New Project**.
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
In the left sidebar, navigate to **APIs & Services → Library**.
Search for **Gmail API**.
Click the Gmail API result and click **Enable**.
#### Step 3: Create a Service Account
In the left sidebar, navigate to **IAM & Admin → Service Accounts**.
Click **+ Create Service Account**.
Fill in the service account details:
* **Name**: e.g. `gmail-connector-reader`
* **Description**: e.g. `Service account for Integrate.io Gmail CSV connector`
Click **Create and Continue**.
Skip the optional role grant steps. Gmail access is controlled via domain-wide delegation, not IAM roles.
Click **Done**.
#### Step 4: Enable Domain-Wide Delegation
From the **Service Accounts** list, click the service account you just created.
Go to the **Details** tab.
Scroll down to **Advanced settings** and find the **Domain-wide Delegation** section.
Click **Enable Google Workspace Domain-wide Delegation**.
Enter a product name (e.g. `Integrate.io Gmail Connector`) and click **Save**.
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
Still on the service account page, go to the **Keys** tab.
Click **Add Key → Create new key**.
Select **JSON** and click **Create**.
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.
Go to [admin.google.com](http://admin.google.com/) and sign in as a Workspace admin.
Navigate to **Security → Access and data control → API controls**.
Click **Manage Domain-Wide Delegation**.
Click **Add new**.
Enter the following:
* **Client ID**: The numeric Client ID from Step 4 (e.g. `118304762983475829341`)
* **OAuth scopes**: `https://www.googleapis.com/auth/gmail.readonly`
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 the Gmail Connection in Integrate.io ETL
Navigate to the **Connections** tab and click **Gmail.**
Fill up the Connection Name
Upload the JSON key you generated in Step 5.
Click **Test Connection** and **Create Connection**
### OAuth 2.0
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.
Navigate to the Connections tab and click + New connection.
Search for and select **Gmail (OAuth)**.
Click Authenticate.
A Google sign-in popup will appear. Select the Google account you want to connect.
Review the requested permissions.
Once authentication completes, fill in the Connection Name (e.g. My Gmail OAuth).
Click Test Connection to verify, then click Create Connection.
Once created, the OAuth connection is maintained automatically: access tokens refresh every 30 minutes in the background, and a token that expires during a job run is renewed using the stored refresh token. To revoke access, remove Integrate.io from your [Google Account permissions](https://myaccount.google.com/permissions), or delete the connection from the Connections page (which also invalidates the refresh token).
## Source Properties
The source component is configured in Step 02 of the component editor.
### Gmail Query
Enter a Gmail search query to filter which emails are fetched. This field supports all standard [Gmail search operators](https://support.google.com/mail/answer/7190).
Examples:
* `from:supplier@example.com has:attachment filename:*.csv`: CSV attachments from a specific sender
* `from:@example.com has:attachment filename:*.csv`: CSV attachments from any sender at a domain
* `subject:"monthly report" has:attachment filename:*.csv`: Emails with a specific subject
* `{from:alice@example.com } has:attachment filename:*.csv`: OR logic across multiple senders
A space between operators means AND, so all conditions must match. Use `OR` (uppercase) or `{}` for OR logic between values of the same operator.
### Read From
Select what to extract from each matching email:
* **Attachments.** Read CSV or Excel attachments from matching emails. Each row in the file becomes a row in the pipeline, with email metadata appended as extra columns. This is the default.
* **Email body.** Read each matching email as a single row. The body, subject, sender, recipient, date, and message ID are exposed as columns. No attachment is required.
Use **Email body** when the data you need lives in the email text itself (for example, transactional notifications, form submissions, or system alerts that don't carry a file). Use **Attachments** when partners or systems send tabular data as CSV or Excel files.
### File Type
This option appears only when **Read From** is set to **Attachments**. Select the format of the attachment files to ingest:
* **CSV.** Comma-separated values
* **Excel.** `.xlsx` / `.xls` spreadsheet files
### Delimiter, Quote Character, and Header Row
These options appear only when **Read From** is set to **Attachments** and **File Type** is **CSV**.
* **Delimiter.** Character that separates fields in the CSV file.
* **Quote character.** Character used to quote field values.
* **File contains a header row.** Check this box if the first row of the file contains column headers. When enabled, the connector uses the header row to name the schema fields. This is checked by default.
### Load Type
Select how records are loaded on each pipeline run:
* **Full Load.** Fetches all emails matching the Gmail query on every run.
* **Incremental Load.** Fetches only emails received after a reference date. The connector appends an `after:YYYY/MM/DD` operator to your Gmail query at runtime so that only new emails are returned by the Gmail API, keeping API usage low and execution fast.
### Incremental Load Settings
When **Incremental Load** is selected, the following options appear:
**Load records.** Select the filter condition:
* `newer than ( > )`: Fetch emails received after the reference date.
**Reference date.** Choose the source of the date value:
* **Last successful run.** Track emails received since the last successful run of this pipeline. Selecting this option auto-fills `incremental_load_date` with the `$_PACKAGE_LAST_SUCCESSFUL_JOB_SUBMISSION_TIMESTAMP` system variable, so each scheduled run picks up only what arrived since the previous run finished. Recommended for scheduled pipelines.
* **Fixed Date.** Select a specific calendar date using the date picker. Use this for a one-time historical backfill.
* **Variable.** Use a custom package variable as the reference date. Select this when you need to drive the start date from a value other than the last successful run timestamp.
**Timezone note**: The Gmail `after:` operator interprets dates in **PST/PDT**, not UTC. If your variable is UTC-based, consider subtracting a 1-day buffer to avoid missing emails near the date boundary.
## Schema
After configuring the source properties, the **Schema** section (Step 03) displays the fields available in the pipeline. The columns depend on the **Read From** mode.
### Attachments Mode
Schema fields are derived from the header row of the first matching email attachment. In addition to the columns from the file itself, the connector appends the following metadata columns to every row:
| Column | Description | Example |
| -------------------- | ------------------------------------------- | --------------------------------------------------------- |
| email\_message\_id | Gmail message ID of the source email | 18d4f2e3a7b1c9d0 |
| email\_date | Date the email was received (ISO 8601, UTC) | 2026-03-10T14:30:00Z |
| attachment\_filename | Original filename of the attachment | sales\_report\_march.csv |
| email\_from | Sender email address | [supplier@example.com](mailto:supplier@example.com) |
| email\_to | Recipient email address | [reports@yourcompany.com](mailto:reports@yourcompany.com) |
| email\_subject | Subject line of the email | Monthly Sales Report |
| email\_body | Plain-text body of the email | Please find the report attached. |
These metadata columns let you trace each row back to its source email and file for deduplication and auditing downstream.
### Email Body Mode
Each matching email produces one row with the following columns:
| Column | Description | Example |
| ------------------ | ------------------------------------------- | ------------------------------------------------- |
| email\_message\_id | Gmail message ID of the source email | 18d4f2e3a7b1c9d0 |
| email\_date | Date the email was received (ISO 8601, UTC) | 2026-03-10T14:30:00Z |
| email\_from | Sender email address | [alerts@example.com](mailto:alerts@example.com) |
| email\_to | Recipient email address | [ops@yourcompany.com](mailto:ops@yourcompany.com) |
| email\_subject | Subject line of the email | Order #12345 confirmed |
| email\_body | Plain-text body of the email | Your order has been confirmed... |
Use a downstream **Select** or **Cross Join with Function** component to parse fields out of `email_body` (for example, with regular expressions) when you need structured values from the email text.
### Example: Extract Order IDs from Notification Emails
Configure the source with:
* **Gmail query:** `from:notifications@example.com subject:"Order confirmed"`
* **Read From:** `Email body`
* **Load Type:** `Incremental Load` with `$package_last_successful_job_submission_timestamp` as the reference date
In a downstream **Select** component, extract the order ID from the body using a regular expression:
```text theme={null}
RegexExtract(email_body, 'Order #(\\d+)', 1) AS order_id
```