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

# Data reference

> Import model, field type mapping, refresh cadence, and limits for the File from Email data source in Adriel.

## 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-sources/a-f/file-from-email/how-to-connect).

## 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:

| Selector          | Behavior                                                                | Applies to                                          |
| ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
| Sender allow-list | Comma-separated sender addresses combined into a `from:` OR group       | Both modes                                          |
| Subject filter    | Substring required in the subject line                                  | Both modes                                          |
| File name filter  | Comma-separated filename fragments; empty value disables name filtering | Attachment mode only                                |
| Search window     | How far back emails are scanned each run                                | One month (attachment) / three days (download link) |

### Delivery modes

The delivery mode is chosen at creation and locked thereafter.

| Aspect            | Attachment                                     | Download link                                               |
| ----------------- | ---------------------------------------------- | ----------------------------------------------------------- |
| File source       | Email attachment binary                        | URL extracted from the email body                           |
| Mailbox filter    | `has:attachment`                               | None — body URLs are extracted programmatically             |
| Size limit        | 25 MB (Gmail attachment cap)                   | No mailbox-side cap                                         |
| IP whitelist      | Not required                                   | The Adriel platform IP must be whitelisted on the link host |
| Deduplication key | Attachment ID (filename + email date)          | Canonical URL                                               |
| Setup validation  | At least one matching email must already exist | Skipped at setup                                            |

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:

| Update method      | Merge behavior                                                                    | Unique key   |
| ------------------ | --------------------------------------------------------------------------------- | ------------ |
| `append` (default) | New rows added; already-synced emails are excluded by mailbox-query deduplication | Not required |
| `upsert`           | Rows merged on the declared unique-key column(s)                                  | Required     |
| `replace`          | The cache table is atomically swapped on each run                                 | Not required |

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

<Note>
  **How to read the columns**

  The **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.
</Note>

Each inferred column type maps to an Adriel field type as follows.

| Inferred column type         | Adriel field type | Data type | Field role                                                   |
| ---------------------------- | ----------------- | --------- | ------------------------------------------------------------ |
| Numeric (integer or decimal) | `number`          | Number    | Metric                                                       |
| Date or timestamp            | `date`            | Date      | Breakdown; enables date-range filtering when mapped at setup |
| Boolean                      | `boolean`         | Boolean   | Metric or breakdown                                          |
| Text (any other value)       | `string`          | Text      | Breakdown                                                    |

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

| Inferred column type | Default aggregation                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| Numeric              | `SUM(x)`                                                                                                    |
| Text                 | Single-value collapse — returns the value when only one distinct value exists in the group, otherwise empty |
| Date or boolean      | Single-value collapse — returns the value when only one distinct value exists in the group, otherwise empty |

## 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](https://support.google.com/mail/answer/6584)). 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:

* [Gmail API — users.messages.list](https://developers.google.com/gmail/api/reference/rest/v1/users.messages/list)
* [Gmail API — search operators](https://support.google.com/mail/answer/7190)

## See also

* [How to connect File from Email](/data-sources/a-f/file-from-email/how-to-connect) (paired how-to)
* [File from SFTP data reference](/data-sources/a-f/file-from-sftp/data-reference) — alternative file feed over SFTP
* [File from OneDrive data reference](/data-sources/a-f/file-from-onedrive/data-reference) — alternative file source from cloud storage