Onboarding Beta - File Specifications

This article will overview how to deliver a file of plaintext or SHA-256 encoded emails and their associated behaviors. Following the directions in this document is required to participate in the Lotame Onboarding BETA program. 


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 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/in/<client_name>/<feed_name>/YYYYMMDD

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.

  1. Segment Membership File

    1. This is the main data file containing your emails and segments. 

    2. Depending on whether you are uploading a JSON or CSV file, this has different filenames. The below sections denote the filenames needed for each.

  2. Done File

    1. The file is empty, but it signifies to Lotame that your upload is complete so we do not accidentally process your file mid-upload. 

    2. Please upload it right after you upload your Segment Membership File.

    3. It must be named YYYYMMDD.done.

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. 

This file must be named segmentmembership.json.gz and is GZIP'd to be space efficient and minimize transfer timings and extra transfer costs of an unzipped file.

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.
idtype String Yes If sending plaintext emails -> email
If sending SHA-256 encoded emails -> email_sha256
segments Array of Strings Yes An array of behaviors you want to associate with the emails.

NOTE: The filename is 

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

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

Below is an example file of plaintext emails:

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

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: segmentmembership_EMAIL.csv
  • SHA-256 Encoded Email: segmentmembership_EMAIL_SHA256.csv
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 file of SHA-256 encoded emails:

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

Below is an example file of plaintext emails:

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