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 ETL pipeline.
Connection
Select an existing Google Mail (Gmail) connection or create a new one. For setup instructions, see Allowing Integrate.io ETL access to my Google Mail (Gmail).
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.
Examples:
from:supplier@example.com has:attachment filename:*.csv: CSV attachments from a specific senderfrom:@example.com has:attachment filename:*.csv: CSV attachments from any sender at a domainsubject:"monthly report" has:attachment filename:*.csv: Emails with a specific subject{from:alice@example.com <from:bob@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:
- Fixed Date. Select a specific calendar date using the date picker. Use this for a one-time historical backfill.
- Variable. Use a system or custom variable as the reference date. The recommended value for scheduled pipelines is
$package_last_successful_job_submission_timestamp, which automatically advances the start date after each successful run.
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 |
| email_to | Recipient email address | 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. |
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 |
| email_to | Recipient email address | 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… |
email_body (for example, with regular expressions) when you need structured values from the email text.
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:
RegexExtract(email_body, 'Order #(\\d+)', 1) AS order_id
