Using Components: Google Mail (Gmail) Source

Use the Google Mail (Gmail) source component to read CSV or Excel file attachments 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 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 <from:bob@example.com>} has:attachment filename:*.csv — OR logic across multiple senders

💡 A space between operators means AND — all conditions must match. Use OR (uppercase) or {} for OR logic between values of the same operator.

File Type

Select the format of the attachment files to ingest:

• CSV — Comma-separated values
• Excel — .xlsx / .xls spreadsheet files

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. These are derived from the header row of the first matching email attachment.

In addition to the columns from the file itself, the connector automatically appends the following metadata columns to every row:

These metadata columns allow you to trace each row back to its source email and file, which is useful for deduplication and auditing downstream in your pipeline.