Onboarding - File Specifications

OVERVIEW

This article will overview how to deliver both Onboarding (emails-to-behaviors) and Onboarding Opt-Out (list of emails to opt-out of Lotame onboarding) files.

---

Supported File Transfer Mechanisms

Lotame will support transfers to a Lotame-hosted S3 bucket for the Onboarding Beta.

There are two methods for connecting to a Lotame-hosted s3:

1. ARN Authentication

   1. Lotame requires the client to provide an ARN of the AWS IAM role that will be used to access the bucket through an automated upload.

2. Access Key and Secret Access 

   1. Lotame will provide the client with an Access Key and Secret for authentication.

   2. This allows clients to use a desktop AWS S3 client to upload files as described on the Onboarding BETA - Manually Uploading Data Files to Lotame S3 page.

Lotame will provide:

1. The AWS S3 bucket name to which to upload files.

2. A directory structure under that bucket that looks like the following:

   1. s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=<DATA_or_OPTOUT>/

      1. <client_id> will be a numerical identifier for the Lotame account this data is being loaded into.

      2. <DATA_or_OPTOUT> DATA is for data files. OPTOUT is opting out emails. These are selected by you are upload time depending on the type of upload you are sending.

      3. This directory structure is explained further in each section below.

Data File Specification

Lotame supports two file types for uploading plaintext emails and SHA-256 encoded emails: JSON and CSV. Descriptions of their formats are below.

These files will be uploaded to the DATA directory: s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=DATA/<filename>

 CSV

Below is the description of the file formatting specs of the CSV file. This file will contain the 1 email in Column 1 with the associated behaviors in the following columns. Each email should only be provided once in a file.

For CSV, the filenames are required to be:

• PlainText Email: <custom_name>_EMAIL.csv
  • Examples:
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL.csv 
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL.csv 
• SHA-256 Encoded Email: <custom_name>_EMAIL_SHA256.csv
  • Examples:
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL_SHA256.csv
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL_SHA256.csv

Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.

Note 2: The EMAIL or EMAIL_SHA256 values in the filename must be uppercased.

Column #	Required?	Description
1	Yes	The plaintext or SHA-256 encoded email.
2..as-many-as-needed	Yes	Each column from 2 on should be a segment you want to associate with the email. Pass as many as needed.

Below is an example CSV file of SHA-256 encoded emails:

9b431636bd164765d63c573c346708846af4f68fe3701a77a3bdd7e7e5166254,Male,AutoBuyer
699af750cdf768a83ca4059ea041da08b86631321f3cedcf5b8ce8f0a872962d,Rock Music,Country
539bbd7479dbf8a353a0e7e25e6570264a912d7b1c10bbe4c645752a98fcee5c,Football,Hockey

Below is an example CSV file of plaintext emails:

user1@example.com,Male,AutoBuyer
user2@example.com,Rock Music,Country
user3@example.com,Football,Hockey

 

JSON

Below is the description of the file formatting specs of the JSON file. This file will contain the emails (plaintext or SHA-256 encoded) and behaviors. Each row in the file is a JSON object for a single email without line breaks. 

The file must be GZIP'd to be space efficient and minimize transfer timings and extra transfer costs of an unzipped file.

For JSON, the filenames are required to be:

• PlainText Email: <custom_filename>_EMAIL.json.gz
  • Examples
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL.json.gz
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL.json.gz
• SHA-256 Encoded Email: <custom_filename>_EMAIL_SHA256.json.gz
  • Examples
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/newsletter_subscribers_EMAIL_SHA256.json.gz
    • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=DATA/website_subscribers_EMAIL_SHA256.json.gz

Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.

Note 2: The EMAIL or EMAIL_SHA256 values in the filename must be uppercased.

Key	Data Type	Required?	Description
userid	String	Yes	The plaintext or SHA-256 encoded email. Note: A userID should only appear once in a given file.
segments	Array of Strings	Yes	An array of behaviors you want to associate with the emails.

Below is an example JSON file of SHA-256 encoded emails:

{"userid":"9b431636bd164765d63c573c346708846af4f68fe3701a77a3bdd7e7e5166254","segments": ["Male","AutoBuyer"]}
{"userid":"699af750cdf768a83ca4059ea041da08b86631321f3cedcf5b8ce8f0a872962d","segments": ["Rock Music", "Country"]}
{"userid":"539bbd7479dbf8a353a0e7e25e6570264a912d7b1c10bbe4c645752a98fcee5c","segments":["Football","Hockey"]}

Below is an example JSON file of plaintext emails:

{"userid":"user1@example.com","segments": ["Male","AutoBuyer"]}
{"userid":"user2@example.com","segments": ["Rock Music", "Country"]}
{"userid":"user3@example.com","segments":["Football","Hockey"]}

Opt-Out File Specification

The Opt-Out file(s) allow you to upload a list of emails that you want opted-out of processing. If there is more than one Opt-Out file uploaded, Lotame processing concatenates them and de-deduplicates them. That combined and deduplicated list is then process across all of your active Data files.

• File Type - CSV
• File Contents - single-column list of emails that you want to be opted-out of processing
• File Upload Location: s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=<client_id>/type=OPTOUT/<filename>
• File Names:
  • PlainText Email: <custom_filename>_EMAIL.csv
    • Examples:
      • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/newsletter_optout_list_EMAIL.csv
      • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/website_optout_list_EMAIL.csv
  • SHA-256 Encoded Email: <custom_filename>_EMAIL_SHA256.csv
    • Examples
      • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/newsletter_optout_list_EMAIL_SHA256.csv
      • s3://lotame-transfer-in-us-east-1/onboarding/in/client_id=12345/type=OPTOUT/website_optout_list_EMAIL_SHA256.csv

Note: The value <custom_name> is created by you. It should be something that you describes your dataset. So if you have multiple files uploaded, you will be able to know which is what when interacting with them in the Lotame Platform UI.

Example for plaintext emails:

user1@example.com
user2@example.com
user3@example.com