Email Retargeting for Publishers

Contents

1. Overview
2. Getting Started
3. Best Practices
4. API Access
5. Syncing Subscribers
6. Subscription Lookup Endpoint
7. DNS Configuration
8. Consuming Campaign Requests

Overview

Traverse Email Retargeting allows marketers to trigger sending publisher-branded email advertisements to your subscribers.

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.

API Access

All API calls are authorized via OAuth 2.0 bearer tokens. To authenticate a request, the access token must be passed in the “Authorization” header, like so:

Authorization: Bearer {your-bearer-token-here}

Please contact us for a token.

Syncing Your Subscriber List

Provide a list of email addresses for recipients you have permission to mail.

To sync your subscriber list:

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

Create subscriber List

Creating subscriber lists programmatically is not yet supported.

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

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

POST https://api.traversedlp.com/v1/list/{YOUR-SUBSCRIBER-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-SUBSCRIBER-LIST-ID-HERE}/recipients?clientId={YOUR-CLIENT-ID}

Managing subscriber 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-SUBSCRIBER-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-SUBSCRIBER-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}.

Subscription Lookup Endpoint

Your subscription lookup endpoint is used when Traverse wants to dispatch a message to a potential recipient on your list. The endpoint should allow Traverse to provide an email hash, and should respond with the subscription status of the corresponding recipient.

The HTTP endpoint should allow for an email hash to be provided like so. Ideally, the endpoint could look up an email based on either SHA1 or MD5 hash. For example:

https://www.publisher.com/subscription/lookup?md5={md5-hashed-email}
https://www.publisher.com/subscription/lookup?sha1={sha1-hashed-email}

This endpoint should return at minimum the plaintext email address, first name, any properties the recipient is currently mailable under, and the CAN-SPAM information (IP, timestamp) for each. The response should be in JSON, and consist of an Array of Objects, each describing a subscription:

* Opt-in providers must provide the subscriptionIp and subscriptionSource fields.

Example Responses

If the recipient is subscribed to multiple properties:

[
  { // First subscription
    email: 'foo@bar.com',
    firstName: 'John',
    propertyId: 'your_property_id_1',
    subscriptionIp: '1.2.3.4',
    subscriptionSource: 'mysite.com'
    subscriptionTimestamp: '2017-07-07T21:27:02+00:00' // ISO-8601 timestamp format
  },
  { // Another subscription
    email: 'foo@bar.com',
    firstName: 'Jonathan', // Maybe they provided a different name for this property.
    propertyId: 'your_property_id_2',
    subscriptionIp: '2.3.4.5',
    subscriptionSource: 'myothersite.com'
    subscriptionTimestamp: '2015-03-02T12:18:01+00:00'
  }
]

If the recipient is not subscribed to any property, or if the publisher doesn’t have a match for the hash:

[] // (No subscriptions)

DNS Configuration

Sending and Receiving Email

If Traverse is doing the send on your behalf(recommended), we will need a domain to mail from. This should either be a subdomain or closely related domain to the domain you already use to send email. Traverse will also need to be able to receive emails at this domain in order to be able to handle complaints.

Once a sending domain has been determined, Traverse will provide you with TXT and CNAME records for you to add to your DNS settings.

Consuming Campaign Requests

Traverse is able to send emails on behalf of our publishers, but some may choose to send the email themselves. We make a campaign request to an endpoint you control when an advertiser wants to send an email to one of your subscribers.

Real-time campaign-request listener

To receive campaign requests in real-time, create an HTTPS listener and let us know the URL.

We will POST JSON objects with the following properties to the URL:

For example:

{
  "campaignId": "6a11644c-690d-4bf3-bb19-4c3efba5a5a5",
  "emailMd5Lower": "1105677c8d9decfa1e36a73ff5fb5531",
  "emailSha1Lower": "ba9d46a037766855efca2730031bfc5db095c654",
  "listIds": ["772823bd-b7be-4d23-bd78-96a577d02765"],
  "advertiserProperties": {
    "impressionId": "f53f6078-f802-4c98-90ca-e90aa56995ab",
    "foo": "bar"
  }
}

Note: If the listener does not promptly reply with an HTTP 2xx status code we may resubmit the request later.