Email Setup Guide

Follow our setup guide to set up a Fivetran Email connection to send files to your destination.

Prerequisites

To set up the Fivetran Email connection, you need a source that sends files as attachments through email.

Setup instructions

1. In the connection setup form, enter the Destination schema of your choice.
2. Enter the Table group name. We combine this with the destination schema to form the Fivetran connection name <destination_schema>.<table_group_name>. This enables you to create multiple Merge Mode connections per destination schema. The Table group name value is used only in Fivetran and does not appear in your destination.
3. Email a sample file to the email address provided in the Send your emails to field to validate attachments.
   We automatically populate the Send your emails to field based on your destination schema and table name.

4. Schedule emails to be sent to the provided email address.

Configure files

• Files - Use this option to map a file name pattern to a destination table.

  • Click + Add files to specify destination tables and their corresponding file name pattern.

  • Table name - Use names that are unique across all S3 connections within the same destination schema.

  • (Optional) File Pattern - Use a regular expression as the file pattern to decide whether or not to sync specific files. If you're unsure what regular expression to use, you can leave this field blank, and we'll sync everything.

  • (Optional) Email Subject - Only attachments from emails with this subject will be synced. Leave this field blank to sync all attachments.

    For example, if you have JSON files with the format report_03122050.json. Use the following regex patterns to decide whether or not to sync specific files:

    • .* matches all files.
    • .*json matches all JSON files.
    • report_\d{2}\d{2}\d{4}\.json matches all the JSON files that begin with the prefix report_ and are followed by a date format of DDMMYYYY or MMDDYYYY.
    We recommend that you test your regex.

  • (Optional) Click Preview Files to validate the file pattern.

  You can skip this intermediate test and proceed to the next step. However, if you choose to skip, we will perform this test once you have finished your configuration.

  • (Optional) Archive File Pattern - Use a regular expression to filter and sync files from archived folders. We sync the files in compressed archives with filenames matching the specified pattern. For example, if you specify the archive folder pattern as .*json, we will sync only the files that end in a .json file extension from the archive folder. You need to configure archive patterns per table. This is useful when an archive folder contains files following different naming patterns, allowing you to route each type to a specific destination table based on its pattern. For example, if the archive folder contains test12.json and check12.json, you can configure test.*\.json as archive pattern for Table1 to sync only test12.json to Table1, and check.*\.json for Table2 to sync only check123.json to Table2.

  • Click Save.

Format

• File Type - We process all files as the selected file type. Use the File Pattern field to select the file extensions you want to sync.

  If your file type is XML, we load your XML data into the _data column without flattening it.

  If your file type is CSV or TSV then enter the following details:

  • (Optional) Delimiter - Specify the delimiter used in your CSV file. If your CSV file uses a custom delimiter, replace the default comma , with your specific delimiter. For example, if your file is tab-delimited, enter \t, or if it’s pipe-delimited, enter |. If you leave this field blank, we’ll attempt to detect the delimiter for each file automatically. However, note that automatic detection may not work in all cases. If your files sync with an incorrect number of columns or use a unique delimiter, consider specifying the delimiter. For more details on how delimiter inference works, see our documentation.
  • Quote character - Typically CSVs use double quotes " to enclose a value. Set the toggle to off if you don’t want to use an enclosing character.
  • Non-Standard escape character - Set the toggle to ON if your CSV generator uses non-standard ways of escaping characters like newline, delimiter, etc. Not standard in CSVs.
  • Null Sequence - Set the toggle to ON if your CSVs use a special value indicating null. Specify the value indicating null only if you are sure your CSVs have a null sequence. Typically, CSVs have no native notion of a null character. However, some CSV generators have created one, using characters such as \N to represent null.
  • Skip Header Lines - Use this option to skip over a fixed number of header lines at the beginning of your CSV files. Set the toggle to ON, and then in the Number of skipped header lines field, specify the number of header lines you want to skip.
  • Skip Footer Lines - Use this option to skip over a fixed number footer lines at the end of your CSV files. Set the toggle to ON, and then in the Number of skipped footer lines field, specify the number of footer lines you want to skip.
  • Headerless files - Set the toggle to ON if your CSV-generating software doesn't provide a header line. Fivetran can generate generic column names and sync data rows with them.
  • Line Separator - Line separators are used in CSV files to separate one row from the next. By default, we use the new line character \n as the line separator. If you use a different line separator for your CSV files, replace \n with your custom line separator.
  If your file type is JSON or JSONL, then select the following:

  JSON Delivery Mode - Use this option to choose how Fivetran should handle your JSON data.

  • Packed: We load all your JSON data into the _data column without flattening it.
  • Unpacked: We flatten one level of columns and infer their data types.
  If your file type is XLS/XLSX/XLSM, then enter the following details:

  By default, we analyze your spreadsheet to identify the cell reference. You can also opt to enter a cell reference of your choice by using the Manually provide cell reference toggle. We use the cell reference to sync all contiguous data starting from the top-left cell in all the spreadsheets matching the name.

  • Analyze sheet: Identify the sample file you would want to sync. We analyze and identify the eligible data sets. To determine the cell reference correctly, do the following:

    • In the Spreadsheet to find data to be synced field, enter the name of the Excel file attached in a recently sent email.
    • Click Analyze sheet.
    • In the Cell reference for syncs drop-down menu, select the cell reference.

  • Set the Manually provide cell reference toggle to ON to enter the cell reference.

    • Manual Cell Reference: Enter the cell reference in the '<sheetName>'!<startColumnName><startRowName> format. For example, if you want to sync data starting from cell 'C3' of the 'Data2' worksheet, enter 'Data2'!C3.

  Learn more about syncing Excel files.

• Primary Key used for file process and load - Use this option to let Fivetran know how you'd like to update the files in your destination. When you modify a previously synced file, the option you select determines if we should replace the rows in the destination table or append new rows to the table:

  • If you select Upsert file using file name and line number, we will upsert your data using the surrogate primary keys _file and _line. If a file has a unique name, we will sync the data for that file as new data.
  • If you select Append file using file modified time, we will upsert your files using surrogate primary keys _file, _line, and _modified. You can track the full history of a file or set of files and your files will have a combination of old and new data or data that is updated periodically.
  • If you select Upsert file using custom primary key, you can keep the most recent version of every record and your files will have a combination of the old and new data or data that is updated periodically. You can choose the primary keys you want to use after you save and test. For more information, see our documentation.
  You can modify the primary keys only if your initial sync fails. If your initial sync is successful, the option to modify the primary keys is not available.

• Compression - If your files are compressed but do not have extensions indicating the compression method, you can decompress them according to the selected compression algorithm. If all of your compressed files are correctly marked with a matching compression extension (.bz2, .gz, .gzip, .tar, or .zip), you can select infer. If you select uncompressed, we do not decompress the files and sync the uncompressed files. If you choose a compression format, we decompress every file using the format you select. For example, if you have an automated CSV output system that GZIPs files to save space but saves them without a .gzip extension, you can set this field to GZIP. We will decompress

Click Save & Test. Fivetran will take it from here.

Fivetran tests and validates the Email connection. On successful completion of the setup tests, you can sync your Email data to your destination.

Setup tests

Fivetran performs the following Email connection tests:

• The Finding tables test validates if you have specified at least one table in the files field to set up the connection.

• The Validating File Pattern Regex test validates the file pattern regex you specified in the setup form. We perform this test only if you specify a regex in the File Pattern field.

• The Validating Archive Pattern test validates the archive pattern regex you specified in the setup form. We perform this test only if you specify a regex in the Archive File Pattern field.

• The Validating EscapeChar test validates the escape character you specified for your CSV files and checks the length of the character which must not be more than one. We perform this test only if you specify an escape character in the Escape Character field.

• The Multi-Character Delimiter Support test validates the length of the delimiter, which must be within 15 characters. We perform this test only if you specify the delimiter for your CSV files in the Delimiter field.

• The "Validating attachments to match file pattern and subject" test verifies whether an email sent to the designated email address mentioned in the Send your emails to field contains attachments that match the file pattern or email subject defined for the configured table. The test succeeds if the connector is able to retrieve at least one and up to five matching attachments for that table.- The Finding Matching Files test checks if the connector can successfully retrieve a minimum of one sample file and a maximum of five sample files for each of the tables you specified in the setup form.

• The Validating Infer FileType test validates whether infer is added as a value in the file_type parameter for connections created using API. We perform this test only if you have set up your connector using API.

Related articles

description Connector Overview

assignment Release Notes

settings API Connection Configuration

home Documentation Home