Skip to main content

​
Introduction

The File from Email connector ingests tabular files — CSV or XLSX — that arrive at a dedicated Adriel mailbox. Files can be delivered either as direct email attachments or as download links embedded in the email body; the customer picks the mode when the data source is created, and it is locked thereafter. A typical use case is a partner or vendor that already emails out scheduled report files — an overnight CSV dump from an ad platform, a weekly reconciliation spreadsheet — to a configured distribution list. The connector watches the mailbox, selects emails matching the configured sender and subject, downloads the file payload, parses it, and writes the rows into the cache. As a file-based connector, the available fields are not a fixed catalog — they are the columns of the ingested file, discovered dynamically after the first successful sync. Numeric columns become metrics and text columns become breakdowns, so widgets can aggregate the imported data alongside platform-native sources without additional configuration. To connect this data source, see How to connect File from Email to Adriel.

​
Data refresh strategy

File from Email uses a simple file cache. The refresh runs on a cron schedule of 0 1,13 * * *, firing twice daily at 01:00 UTC and 13:00 UTC. On each run, the connector issues a mailbox query for emails matching the configured sender(s) and subject within the mode-specific time window — one month for attachments, three days for download links — downloads each new payload, parses it, and merges the rows according to the configured update method. The active merge strategy depends on the update method: append and upsert use UPSERT semantics; replace atomically swaps the cache table. End users cannot trigger a refresh from the dashboard UI (allowUserManualRefresh = false). An internal manual cache-refresh capability exists with a quota of one run per day.

​
Architecture levels

Dedicated mailbox → matching email → file payload → parsed rows → cache table. The connector reads from a single mailbox dedicated to the data source. The customer does not host the inbox — the receiving address and credentials are managed centrally by Adriel.
  • Sender allow-list. One or more sender addresses define the allow-list; only messages from those senders are considered.
  • Subject filter. An optional subject substring narrows the match further.
  • Receiver override. An optional receiver-address override directs the connector at a non-default destination; otherwise a per-workspace address is derived automatically.
  • Multi-file behavior. Every new matching email’s payload is processed on each run. Deduplication ensures the same email is not reprocessed across runs.
One Adriel data source binds to one mailbox configuration. To ingest a separate feed, create a second data source.

​
Date range limits

There is no platform-imposed date range limit, and the connector provides no built-in date breakdown (hasDateBreakdown = false). Date bounds are defined by the contents of the source file. A date column, when present in the file, is mapped during data-source setup and enables date-range filtering on the dashboard; without a mapped date column, all rows are treated as a single snapshot set. The mode-specific mailbox search window — one month for attachments, three days for download links — caps only how far back emails are scanned on each refresh, not the dashboard date range itself.

​
Import model

Files are matched and imported by watching the dedicated mailbox. Authentication to the mailbox is handled centrally through a Gmail service account (gmail.readonly scope) — the customer does not supply OAuth credentials. Setup consists of choosing the delivery mode, supplying the sender allow-list and subject filter, and, for upsert mode, declaring the unique-key column.

​
Email and file matching

The mailbox query combines the configured selectors:

​
Delivery modes

The delivery mode is chosen at creation and locked thereafter. In download-link mode, the email’s text is analyzed to identify downloadable file URLs, which are then fetched over HTTPS. Qualifying links point to csv, tsv, xls, xlsx, zip, gz, or jsonl files.

​
File parsing

  • Supported formats. CSV (header row required) and XLSX. For XLSX workbooks, only the first non-empty sheet is converted to rows; other sheets are silently ignored.
  • Header row. The first row of the file is treated as the header by default; the header-row index and the data-start column are configurable options.
  • Header sanitization. Dots (.) in header cells are replaced with spaces to keep column names valid downstream.
  • Column discovery. After the first successful sync, the available fields are read from the actual columns of the cache table.

​
Update methods

Three update methods control how new file rows merge with existing cache contents:

​
Field type mapping

File from Email is free-format: no metric or breakdown schema is predefined. The available fields are the columns of the ingested file, and each column’s type is inferred by sampling up to 500 rows of the source data. Numeric columns become metrics; text columns become breakdowns.
How to read the columnsThe Data type column uses the platform’s ten-value vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. The Field role column indicates whether the field can serve as a metric, a breakdown, or both.
Each inferred column type maps to an Adriel field type as follows.

​
Adriel-added fields

The connector adds no synthetic user-facing fields on top of the file’s own columns. Several internal cache-bookkeeping columns are written to the cache table but excluded from the available-fields list shown to customers: id, filename, file_updated_at, created_at, and updated_at.

​
Aggregation defaults

When no explicit aggregation is set on a field, the query builder chooses one based on the inferred column type.

​
Limitations

Based on the current connector:
  • Delivery mode is locked at creation. The choice between attachment and download-link mode cannot be changed after the data source is created; switching requires a new data source.
  • 25 MB attachment cap. Attachment-mode files are subject to the 25 MB Gmail attachment limit (Gmail Help — attachment size limits). Download-link mode has no mailbox-side size cap.
  • XLSX first-sheet only. Only the first non-empty sheet of an XLSX workbook is parsed. Pre-consolidate or split sheets into separate files when multiple are relevant.
  • Attachment mode validates at setup. Creating an attachment-mode data source fails with NO_FILE_MATCHING_SETTING if no matching email already exists in the mailbox. Download-link mode skips this check.
  • IP whitelist for download-link hosts. Many vendor-hosted export links restrict access by IP. The Adriel platform IP must be whitelisted on the link host; a 403 response surfaces as NEED_WHITELIST_IP_FOR_DOWNLOAD_LINK.
  • Schema stability required. A file whose column count does not match the existing schema disconnects the data source (INVALID_CSV_MISMATCHED_COLUMN_COUNT), as does a column whose type does not match on cache insert (CSV_COLUMN_TYPE_MISMATCHED).
  • Upsert requires a unique key. Selecting the upsert update method without declaring a unique-key column fails validation at creation (INVALID_OPTION_COMBINATION).
  • No built-in date breakdown. The connector provides no automatic date-range breakdown; date filtering depends on a date column being mapped at setup.
  • No user-triggered refresh. End users cannot refresh the data source from the dashboard UI; the cache refreshes on the twice-daily schedule.

​
API references

File from Email uses centrally managed infrastructure and exposes no customer-facing API. For the underlying delivery mechanism, see:

​
See also