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.

---

EMAIL File Specifications

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 one email in Column 1 and associated behaviors in the following columns. Each email should only be provided once in a file.

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 newsletter_subscribers_EMAIL_SHA256.csv:

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

Below is an example CSV file of plaintext emails newsletter_subscribers_EMAIL.csv:

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. 

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 newsletter_subscribers_EMAIL_SHA256.json:

{"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 newsletter_subscribers_EMAIL.json:

{"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.

This file format is straightforward, it is a single-column list of emails that you want to be opted-out of processing

 Example for plaintext emails newsletter_subscribers_OPTOUT_EMAIL_SHA256.csv:

9b431636bd164765d63c573c346708846af4f68fe3701a77a3bdd7e7e5166254
699af750cdf768a83ca4059ea041da08b86631321f3cedcf5b8ce8f0a872962d
539bbd7479dbf8a353a0e7e25e6570264a912d7b1c10bbe4c645752a98fcee5c

Example for plaintext emails newsletter_subscribers_OPTOUT_EMAIL.csv:

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