Activity Notification

Contents

  1. Overview
  2. Getting started
  3. Best practices
  4. Syncing your activation list
  5. Receiving activity notifications

Overview

Traverse Activity Notification allows marketers to be notified when hashes are active on our network.

Getting started

To get started with Traverse Activity Notification:

  1. Review the best practices.
  2. Sync your activation list.
  3. Receive activity notifications.

Best Practices

While we make every attempt to maintain the availability of our system, unexpected errors may occur:

  1. Always check whether the HTTP status code is 2xx (success) before proceeding, and abort if not.
  2. If the status code is 4xx (client error), your request is likely invalid. Review the documentation before retrying.
  3. If the status code is 5xx (server error), there is likely a problem on our end. Please retry after 60 seconds.
  4. Otherwise, treat any unexpected response, status code, timeout or exception as a 5xx.
  5. Log your requests and replies, and monitor for and review any failures.

Syncing Your Activation List

When we see an email from your activation list, we will send you a notification.

To sync your activation list:

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

Create activation List

Creating activation lists programmatically is not yet supported.

In the meantime, please contact us and we will provide you a activation-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 activation 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:

Adding activation Emails Programmatically

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

POST https://api.traversedlp.com/v1/list/{YOUR-ACTIVATION-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:

Property Value
emailMd5Lower MD5 hash of trimmed, lowercased email address
emailSha1Lower SHA-1 hash of trimmed, lowercased email address

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-ACTIVATION-LIST-ID-HERE}/recipients?clientId={YOUR-CLIENT-ID}

Managing activation 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-ACTIVATION-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-ACTIVATION-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}.

Receiving activity notifications

We will send you an activity notification each time we see a hash you are interested in, based on configuration. For example, this could be each time we see email-based traffic, traffic from hashes on your activation list or some combination of complex logic. Let us know what data you are interested in.

An activity notification may contain the following fields†:

Parameter Description Always Provided?
emailMd5Lower An MD5 hash of a lowercased email address No*
emailSha1Lower A SHA-1 hash of a lowercased email address No*
emailSha256Lower A SHA-256 hash of a lowercased email address No*
timestamp ISO-8601 format timestamp of roughly when we saw the email being active Yes
listIds A stringified JSON array of lists of yours that this hash is on, if you are limiting to lists. No†
type How the user was interacting when we captured the activity No†
channel Where the user was interacting when we captured the activity. email, web, or mobile No†
source How Traverse ingested the activity. Either “container,” “pixel,” or “snapshot.” No†
ip The IP address of the active user No†
userAgent The User Agent string of the active user No†
publisherId The Traverse Id of the publisher who provided this data No†
publisherSubId The id Traverse’s publisher has assigned to their publisher who provided this data No†

*Note: At least one of emailMd5Lower, emailSha1Lower, emailSha256Lower will always be provided.

† Note: Depending on your integration, not all fields will be provided.

Activity notification endpoint

We can send an HTTP POST or GET request to an HTTPS listener of your choice each time we see activity you are interested in. The endpoint will be called with url parameters or sent a JSON object representing an activity notification. Responding with a 2xx response will indicate to us that you were able to process properly. Other codes will result in us resending the message at a later time.

Example POST to your endpoint

curl -H "Content-Type: application/json" -X POST -d '{"emailMd5Lower":"99660bb599b42f2e982b0a793e99670c","timestamp":"2017-06-07T15:47:12.305Z"}' "https://yourcompany.com/traverseListener"

Example GET to your endpoint

We can use our parameter names:

curl "https://yourcompany.com/traverseListener?emailMd5Lower=99660bb599b42f2e982b0a793e99670c&timestamp=2017-06-07T15:47:12.305Z"

Or we can use parameters that work more cleanly for your stack:

curl "https://yourcompany.com/traverseListener?md5=99660bb599b42f2e982b0a793e99670c&ts=2017-06-07T15:47:12.305Z"

Activity notification AWS Firehose

If your infrastructure is in AWS and you would like to set up an Amazon Kinesis Firehose, we can send activities directly to that, instead of to an HTTP listener, so you can process the batched files as you need. Depending on how much activity you are interested in, the full stream of activity data sent through HTTP requests may be too expensive for you to want to handle with servers in realtime. If you would like to use the Firehose, contact us and we will help get you set up with Cloudformation Templates.