Real-Time Openers

AtData's Real-Time Openers (RTO) service maintains a list of your email addresses in the form of MD5 hashes. Whenever we see one of your email addresses open an email message across our publisher network, we send you a notification of that open with an a second of the open event. You can use this information to trigger your own email while the individual is in their inbox, which boosts open rates by approximately 20%.

To use the RTO service, you send us a list of email addresses to monitor and setup a web service on your servers to receive notifications of open events.

You can programmatically update the email list we maintain for you by sending add and delete files to keep your database current. These files consist of either plaintext or MD5 email addresses:

• Add Files: Contents are added to your existing database. Duplicate records are ignored.
• Delete Files: Contents are removed from your database. Records not found in the database are ignored.

📘

Important

If you post a file of MD5-hashed email addresses, the MD5s should be 32-character strings consisting only of alphanumeric ascii characters in the [0-9] and[a-f] range. Alternate representations such as MD5s starting with "0x" will not work.

Methods to Update Your RTO Database

You can update your standing RTO database in the following ways:

Add/Delete via InstantData

In your InstantData account, navigate to the API Keys tab and select your RTO key. From the Actions menu, you can post files to add or delete from your RTO database.

Add/Delete via the List API

You can also submit add and delete files via the List API, which is recommended for automated processing. You can submit as many files as you need per day. The following is an example of using the List API to upload a file:

curl --request POST \
     --url 'https://api.atdata.com/v5/list?&header=true&delimiter=,&type=targeting&action=add&md5_email=1&name=LOAD_FILE.csv' \
     --header 'Content-Type:multipart/form-data' \
     --header 'api_key: <YOUR_API_KEY_HERE>' \
     --file "file=@LOAD_FILE.csv"

This request accepts the following query parameters:

• type: Should be set to targeting, indicating the emails you wish to receive open signals for.
• action: Indicates whether the file is for adding or deleting records. Possible values are add or delete.
• md5_email=1: Specifies that the file contains MD5 hashed email addresses. If not set, it is assumed the file contains plain text emails.
• name: The name of the file being loaded. Example: LOAD_FILE.csv.

File Requirements

Ensure that the file is in the format specified below:

• Files must be in CSV format with a single column containing either plaintext or MD5 email addresses.
• For plaintext emails, use the email parameter instead of md5_email.
• Files cannot mix plaintext emails and MD5 hashes within a single file.
• The header parameter is optional and can be set to true or false.

🚧

RTO Key

Remember to replace <YOUR_API_KEY_HERE> with you actual RTO Key.

Retrieving the List ID and Checking the Status:

After posting a file, the initial API call will return a List ID:

{
  "list_id": 1098764,
  "size_bytes": 3304
}

You can use this list_id to confirm the completion of your file upload with the request below:

curl --request GET \
     --url https://api.atdata.com/v5/list/1098764 \
     --header 'accept: application/json' \
     --header 'api_key: <YOUR_API_KEY_HERE>'

This will return a JSON similar to the following:

{
  "list_id": 1098764,
  "name": "LOAD_FILE.csv",
  "status": "Results",
  "records": 100,
  "size_bytes": 3304,
  "created_at": "2023-04-13T17:21:01Z"
}

A status of "Results" indicates that the upload process is complete.

📘

Important

This method is only for updating the database and cannot be used to retrieve data.