Email List Management

Syncing Your List

Lists can be integrated in our system in multiple ways: recipient lists, exclusion lists, etc.

To sync your list:

1. Create your list.
2. Send us a batch of emails on the list.
3. Connect us to a feed of your new emails.

Create List

Creating lists programmatically is not yet supported.

In the meantime, please contact us and we will provide you a -list ID and an authentication token if needed, as well as details about how to best send us your list. In general, S3 and SFTP are the best methods and we can provide an account on our SFTP server if needed.

Adding Emails Batch

Traverse is able to receive email lists as CSV or TSV files. Each row should be MD5, SHA-1 and SHA-256 hashes (in that order) of the lowercased versions of one email. Hosting this file on Amazon S3 works best. We can also pull your file from an SFTP or provide an SFTP account on our platform.

If you have any questions about getting set up with an SFTP account or providing us an S3 link, your account manager will be happy to assist.

File Formatting

Files must be in CSV or TSV format. Header rows are optional but supported.

Example CSV

99660bb599b42f2e982b0a793e99670c,402e9f64675aaa8c434a60d140f1a329e8f5e972,a7fead559ee33a9fa378ff3312d0875b41c052070e03c022c64078ed1c402109
53f84e68440893fb0653276084c7df5c,e81614f66e0cd98b97f7a6124ce9041ad70139ac,028520766f9d70b663b20e97e468c4de823b32e61448341c816e6a9e74ecde2b

Example TSV

99660bb599b42f2e982b0a793e99670c	402e9f64675aaa8c434a60d140f1a329e8f5e972	a7fead559ee33a9fa378ff3312d0875b41c052070e03c022c64078ed1c402109
53f84e68440893fb0653276084c7df5c	e81614f66e0cd98b97f7a6124ce9041ad70139ac	028520766f9d70b663b20e97e468c4de823b32e61448341c816e6a9e74ecde2b

SFTP Upload Guidelines

When uploading email batches to our SFTP folder, please adhere to the following:

• Filenames must be unique. Including the date is recommended (i.e. unsub-2018-01-01.csv).
• When using a Traverse-hosted SFTP account, files should be uploaded to the incoming directory.
• Filenames must have the correct file extension for their type.

Adding Emails Programmatically

To add emails to a list, use the following authenticated endpoint:

POST https://api.traversedlp.com/v1/list/{YOUR--LIST-ID-HERE}/recipients?clientId={YOUR-CLIENT-ID}

Send the authorization header with the value bearer {YOUR-AUTH-TOKEN}.

The message body should be an array of up to 100 JSON objects representing recipients, each with the following properties:

For example:

[
  {
    emailMd5Lower: "1105677c8d9decfa1e36a73ff5fb5531",
    emailSha1Lower: "ba9d46a037766855efca2730031bfc5db095c654"
  },
  {
    emailMd5Lower: "acbd18db4cc2f85cedef654fccc4a4d8",
    emailSha1Lower: "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"
  }
]

An example request, using curl might look like this:

curl -H 'authorization: bearer {YOUR-AUTH-TOKEN}' -H "Content-Type: application/json" -X POST -d '[{"emailMd5Lower":"1105677c8d9decfa1e36a73ff5fb5531","emailSha1Lower":"ba9d46a037766855efca2730031bfc5db095c654"}]' https://api.traversedlp.com/v1/list/{YOUR--LIST-ID-HERE}/recipients?clientId={YOUR-CLIENT-ID}

Managing Email Lists

Our API also supports looking up and deleting emails from your list by MD5 hash.

To look up whether an email is on your list, use the following authenticated endpoint:

GET https://api.traversedlp.com/v1/list/{YOUR--LIST-ID-HERE}/{emailMd5Lower}

Our API will return a 200 response with the emailMd5Lower and emailSha1Lower (if provided), as well as other metadata.

To delete an individual from your list, use the following authenticated endpoint:

DELETE https://api.traversedlp.com/v1/list/{YOUR--LIST-ID-HERE}/{emailMd5Lower}

Our API will return a 200 response if the email is delted, or a 404 if the address was not found on the list.

Note: For each of these requests, send the authorization header with the value bearer {YOUR-AUTH-TOKEN}.