Using DataValidation's API


Getting Started

In order to use DataValidation's API, you must first acquire a personal API key. To receive an API key, sign up for the free API plan by clicking here. It may take around 24 hours to be approved. Once you have received your API key, you are ready to start using the API. This API can be used for realtime email validation, email list validation, deliverability reports, and Email Assurance. Email service providers have access to ESP-wide Email Assurance, including onboarding reports, ongoing monitoring, and automated list maintenance.


Swagger Docs

Please note the Authorization header must include "Authorization: bearer {API Key}" in each request.


 


Using the Realtime Email Validation Endpoint


Examples

This API can be used to validate a single email address and can be used for sign up forms, short lists or just simple email verification. An Email Assurance grade - ranging from A+ to F - and historical deliverability data is provided with each email address.

The sample data below will be used repeatedly throughout the following examples. “API key” represents a custom API that you should receive after signing up for an API plan. “Email” represents an email address that you are interested in querying. To recreate these examples, substitute your personal API key and email address of interest.

Email:  john.doe@example.com

API Key:  1234567890

Example using curl

“curl” is a command line tool that allows you to make web requests and receive responses from a website or API by means of console input. “curl” is available on Mac, Unix, and Windows operating systems.

Using the sample data above, a curl request to the Realtime API would be constructed as follows:

$ curl -header “Authorization: bearer 1234567890” https://api.datavalidation.com/1.0/rt/john.doe@example.com/


Example using Python and requests

import requests

headers = {“Authorization”: “bearer 1234567890”}
url = “http://api.datavalidation.com/1.0/rt/john.doe@example.com/”
response = requests.get(url, headers=headers)

print(response.json())

The above examples should yield results similar to the following:

{"Address": "john.doe@example.com", "grade": "A", "click": "K0", "open": "R0", "hard": "H4", "optout": "O4", "complain": "W4", "trap": "T4", "deceased": "D4"}


For detailed information about the result codes, click here.


Formatting

If you would prefer nicely formatted output in your responses, add “?pretty=true” to the end of your url like the example below:

https://api.datavaildation.com/1.0/rt/john.doe@example.com/?pretty=true

formatted response example:

{
   "Address": "john.doe@example.com",
   "grade": "A",
   "click": "K1",
   "open": "R1",
   "hard": "H3",
   "optout": "O4",
   "complain": "W3",
   "trap": "T4",
   "deceased": "D4"
}


Troubleshooting

If you attempted to make a Realtime API request but instead received an error, check the following for troubleshooting tips.

301 Moved Permanently:

  • Make sure you specified “https” and not “http”

302 Redirect:

  • Ensure url ends with ‘/’

403 Forbidden:

  • Ensure header was specified in request
  • Check for spelling mistakes in header section
  • The header section is case sensitive also
  • Ensure API key is accurate

404 Not Found:

  • Check your url for accuracy

500 Internal Error:

  • Status code 500 is indicative of an internal server error
  • We are likely aware of the problem and working on it
  • Feel free to contact us at support@datavalidation.com for additional information


For detailed information about the result codes, click here.


Using the Batch Email Validation API


This API can be used to verify a list of email addresses, access deliverability reports, and integrate Email Assurance. Email service providers can use this API to onboard new users, monitor current users, and automate list maintenance.

View the current swagger docs at the top of this document.


View the Deliverability of an Email List

Follow these steps to retrieve the Email Assurance Report, which is a breakdown of a list's Email Assurance Grades and Deliverability Codes.

Uploading a List

As an ESP, it may be useful to know the quality of a potential user's list(s) before accepting them as a customer. This set of instructions will provide a means of doing so.

Before upload a list, a few questions must first be answered about the list being uploaded:

  • Does the csv have include a header on the first row?

    If yes, the query parameter 'header' should be set to 'true', otherwise 'false'.

  • What collumn is the email address in?

    If the email address is in the first collumn, the query parameter 'email' should be set to '0'. If the email address is in the second collumn, it should be set to '1' etc.

  • Is there data in each row (other than the email address) that you would like to store?

    You might want to store additional data such as first name, last name, unqiue ID etc. If so, the query parameter 'metadata' should be set to 'true', otherwise 'false'.

After adding a list, individual member grades will be available via this endpoint: /list/{listslug}/member/{memberslug}/

'memberslug' is a unique ID specific to members in a list. If you prefer to specify 'memberslug', set the 'slug_col' query parameter to the collumn containing your provided identifier in your csv(collumn 1 = 0). If this parameter is not provided, member slugs will be generated automatically.

Note: If you intend on accessing individual member grades and not ALL member grades, be sure to include member slugs in your csv. Otherwise, you will have to make a call to '/list/{listslug}/member/' to retrieve the memberslugs we provide and you will be charged a remediation token for each member in the list.

Sample command:

$ curl -X POST
-H "Content-Type: text/csv
    Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/?header=true&email=0&metadata=true&slug_col=2"
-d "email_address,first_name,ID,
    foo@example.com,foo,001,
    bar@example.com,bar,002,
    baz@example.com,baz,003,"

Sample output:

{
    "list": [
        {
            "status": "new",
            "size": 0,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/Ko3yuDOI/",
                "links": {
                    "jobs": "job/",
                    "batch_subscribe": "subscribe.csv",
                    "member": "member/{member_slug}/",
                    "job": "job/{job_slug}/",
                    "batch_unsubscribe": "unsubscribe.csv",
                    "export": "export.csv",
                    "members": "member/"
                }
            },
            "slug": "Ko3yuDOI",
            "metadata": {}
        }
    ]
}

Be sure to store the slug, as this will be needed to access the list in the future.

Running a Job

To begin processing a list, a job must be created to start validating members within a list.

Note: An Onboarding Token will be charged for each member in the list when a job is created.

Command:

$ curl -X POST
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/job"

Sample output:

{
    "job": [
        {
            "status": "New",
            "list_slug": "JItNx3th",
            "stats": {},
            "created": "2014-10-15 14:36:21.749000",
            "webhook": {
                "status": null,
                "complete": null
            },
            "priority": {
                "mu": 10,
                "sigma": 0
            },
            "original_chunks": null,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/JItNx3th/job/XdH8rZQk/"
            },
            "current_chunks": null,
            "pct_complete": 0,
            "slug": "XdH8rZQk"
        }
    ]
}

If the list is large or we currently have a large number of list members to validate in our queue, it may take some time to validate the members in your list.

To view the progress of a validation job, construct the following request using the job's slug from the above result:

Command:

$ curl -X GET
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/job/{job_slug}/"

If the job is not finished, you should see a response similar to:

{
    "job": [
        {
            "status": "New",
            "list_slug": "Ko3yuDOI",
            "stats": {},
            "created": "2014-10-15 15:29:28.335000",
            "webhook": {
                "status": null,
                "complete": null
            },
            "priority": {
                "mu": 10,
                "sigma": 0
            },
            "original_chunks": null,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/Ko3yuDOI/job/XLoklKeI/"
            },
            "current_chunks": null,
            "pct_complete": 0,
            "slug": "XLoklKeI"
        }
    ]
}

Notice the 'pct_complete' field representing the current percent of completion.

Viewing Deliverability Report

After a job is complete, repeating the GET request from above will yield a response similar to:

{
    "job": [
        {
            "status": "Ready",
            "list_slug": "E5RIlS2B",
            "stats": {
                "optout": {
                    "O4": 3
                },
                "grade": {
                    "D": 3
                },
                "hard": {
                    "H4": 3
                },
                "complain": {
                    "W4": 2,
                    "W3": 1
                },
                "trap": {
                    "T4": 2,
                    "T1": 1
                },
                "open": {
                    "R0": 3
                },
                "click": {
                    "K0": 3
                },
                "deceased": {
                    "D4": 3
                }
            },
            "created": "2014-10-15 20:46:53.218000",
            "webhook": {
                "status": null,
                "complete": null
            },
            "priority": {
                "mu": 10,
                "sigma": 0
            },
            "original_chunks": 2,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/job/zJSSU1HE/"
            },
            "current_chunks": 0,
            "pct_complete": 100,
            "slug": "zJSSU1HE"
        }
    ]
} 

Validate an Email List

After reviewing the overall grades of a list, it may or may not be necessary to remediate the list. The DataValidation API provides multiple methods for viewing validation grades for individual members of a list.

To retrieve individual member grades for ALL members of a list:

Using the '/export.csv' endpoint will provide csv formatted output including only the member slugs, email addresses, and grades.

/list/{list_slug}/export.csv:

Command:

        curl -X GET -H "Authorization: bearer {api_key}" "https://api.datavalidation.com/1.0/list/{list_slug}/export.csv"

Sample output:

BPopxToE,foo@example.com,D,K0,R0,H4,O4,W3,T4,D4
FVCExahe,baz@example.com,D,K0,R0,H4,O4,W4,T1,D4
MPM-h7D1,bar@example.com,D,K0,R0,H4,O4,W4,T4,D4

/list/{list_slug}/member/:

Using the '/member/' endpoint will provide json formatted output including member slugs, member email addresses, update timestamps as well as any metadata that may have been included in the list.

Command:

        curl -X GET -H "Authorization: bearer {api_key}" "https://api.datavalidation.com/1.0/list/{list_slug}/member/"

Sample output:

{
    "members": [
        {
            "updated": "2014-10-15 20:45:13.803000",
            "list_slug": "E5RIlS2B",
            "analysis": {
                "optout": "O4",
                "grade": "D",
                "hard": "H4",
                "click": "K0",
                "trap": "T4",
                "open": "R0",
                "complain": "W4",
                "deceased": "D4"
            },
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/member/MPM-h7D1/"
            },
            "f_upload": false,
            "address": "bar@example.com",
            "slug": "MPM-h7D1",
            "metadata": {
                "": "",
                "first_name": "bar",
                "email_address": "bar@example.com",
                "ID": "002"
            }
        },
        {
            "updated": "2014-10-15 20:45:13.802000",
            "list_slug": "E5RIlS2B",
            "analysis": {
                "optout": "O4",
                "grade": "D",
                "hard": "H4",
                "click": "K0",
                "trap": "T4",
                "open": "R0",
                "complain": "W3",
                "deceased": "D4"
            },
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/member/BPopxToE/"
            },
            "f_upload": false,
            "address": "foo@example.com",
            "slug": "BPopxToE",
            "metadata": {
                "": "",
                "first_name": "foo",
                "email_address": "foo@example.com",
                "ID": "001"
            }
        },
        {
            "updated": "2014-10-15 20:45:13.803000",
            "list_slug": "E5RIlS2B",
            "analysis": {
                "optout": "O4",
                "grade": "D",
                "hard": "H4",
                "click": "K0",
                "trap": "T1",
                "open": "R0",
                "complain": "W4",
                "deceased": "D4"
            },
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/member/FVCExahe/"
            },
            "f_upload": false,
            "address": "baz@example.com",
            "slug": "FVCExahe",
            "metadata": {
                "": "",
                "first_name": "baz",
                "email_address": "baz@example.com",
                "ID": "003"
            }
        }
    ]
}

A Remediation Token will be charged for EACH member in a list when using the '/export.csv' or '/member/' endpoints to retrieve member grades.

To retrieve individual grades for a single member of a list:

Using the '/member/{member_slug}/' endpoint will provide output similar to the '/member/' endpoint above but for just a single member.

/list/{listslug}/member/{memberslug}/:

Command:

        curl -X GET -H "Authorization: bearer {api_key}" "https://api.datavalidation.com/1.0/list/{list_slug}/member/"

Sample output:

{
    "members": [
        {
            "updated": "2014-10-15 20:45:13.802000",
            "list_slug": "E5RIlS2B",
            "analysis": {
                "optout": "O4",
                "grade": "D",
                "hard": "H4",
                "click": "K0",
                "trap": "T4",
                "open": "R0",
                "complain": "W3",
                "deceased": "D4"
            },
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/member/BPopxToE/"
            },
            "f_upload": false,
            "address": "foo@example.com",
            "slug": "BPopxToE",
            "metadata": {
                "": "",
                "first_name": "foo",
                "email_address": "foo@example.com",
                "ID": "001"
            }
        }
    ]
}

A single Remediation Token will be charged for each call to the '/member/{member_slug}' endpoint.

Remediating an Existing List

Important!

30 days after a list has been uploaded, list members that have not been updated will be removed from our system, potentially resulting in the absence of some or all list members. If you require remediation of a list that is more than 30 days old, it is important to re-upload the list. If your list is less than 30 days old, the remediation process is the same as above.

Integrating Email Assurance

For a more detailed account, please refer to our Email Assurance Cookbook for ESPs.

The following process should be repeated (in addition to the steps above) in order to monitor your list(s) and keep them up to date with respect to new subscribers, unsubscribes, and grade changes. This process should be used if you are setting up daily or weekly monitoring and remediation. Please use this endpoint in place of the list/listslug/{csvlink}/import endpoint if you are monitoring lists daily or weekly.

Resetting the 'changed' Flag

First, you will want to reset the changed flag on the members of a list. The following command will set the changed flag to false for each member in a list.

/list/{list_slug}/member/:

Command:

curl -X PATCH
-H "Authorization: bearer {api_key}"
-H "Content-Type: application/json"
"https://api/datavalidation.com/1.0/list/{list_slug}/member/"
-d "{'changed':false}"

Sample output:

{
    "updated": -1,
    "unsubscribed": 0,
    "subscribed": 0
}

Removing Unsubscribes

After resetting the 'changed' flag for list members, you should remove members from a list that have unsubscribed. The following command will remove specified members from a list by supplying CSV input via POST to the unsubscribe.csv endpoint.

/list/{list_slug}/unsubscribe.csv

Parameters:

name: header
paramType: query
description: Is there a header row present in the CSV data
required: true
type: boolean

name: slug_col
paramType: query    
required: true
description: The column in the csv containing the slug for each member.
type: integer

Command:

curl -X POST
-H "Content-Type: text/csv"
-H "Authorization: bearer {api_key}"
   "https://api.datavalidation.com/1.0/list/{list_slug}/unsubscribe.csv?header=true&slug_col=2"
-d "email_address,first_name,ID,
    oof@example.com,oof,005,
    rab@example.com,rab,006,
    zab@example.com,zab,007"

Sample output:

{
    "list": [
        {
            "status": "new",
            "size": 3,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/{list_slug}/",
                "links": {
                    "jobs": "job/",
                    "batch_subscribe": "subscribe.csv",
                    "member": "member/{member_slug}/",
                    "job": "job/{job_slug}/",
                    "batch_unsubscribe": "unsubscribe.csv",
                    "export": "export.csv",
                    "members": "member/"
                }
            },
            "slug": "E5RIlS2B",
            "metadata": {}
        }
    ]
}

Adding New Subscribers

Once unsubscribed members have been removed, you will want to add any new subscribers to the list. The following command will add specified members to a list by supplying CSV input via POST to the subscribe.csv endpoint.

/list/{list_slug}/subscribe.csv

Parameters:

name: header
paramType: query
description: Is there a header row present in the CSV data
required: true
type: boolean

name: email_col
paramType: query
description: Which column is the email address in? (0 = first column)
required: true
type: integer

name: metadata
paramType: query
description: Should the metadata (non-email) in the CSV be stored? (true or false)
required: true
type: string
format: other

name: slug_col
paramType: query
description: The column in the csv containing a slug for each member. If this is omitted, a slug will be generated automatically.
required: false
type: integer

Command:

curl -X POST
-H "Content-Type: text/csv"
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/subscribe.csv?header=true&email=0&metadata=true&member_slug=2"
-d "email_address,first_name,ID,
    oof@example.com,oof,005,
    rab@example.com,rab,006,
    baz@example.com,baz,007,"

Sample output:

{
    "list": [
        {
            "status": "new",
            "size": 6,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/E5RIlS2B/",
                "links": {
                    "jobs": "job/",
                    "batch_subscribe": "subscribe.csv",
                    "member": "member/{member_slug}/",
                    "job": "job/{job_slug}/",
                    "batch_unsubscribe": "unsubscribe.csv",
                    "export": "export.csv",
                    "members": "member/"
                }
            },
            "slug": "E5RIlS2B",
            "metadata": {}
        }
    ]
}

Running Validation

Now that your list has been updated with new subscribers, it's time to run a validation job. To run validation, send a POST request to the /list/job/ endpoint.

Command:

curl -X POST
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/job/"

Sample output:

{
    "job": [
        {
            "status": "New",
            "list_slug": "{list_slug}",
            "stats": {},
            "created": "2014-10-15 14:36:21.749000",
            "webhook": {
                "status": null,
                "complete": null
            },
            "priority": {
                "mu": 10,
                "sigma": 0
            },
            "original_chunks": null,
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/JItNx3th/job/{job_slug}/"
            },
            "current_chunks": null,
            "pct_complete": 0,
            "slug": "{job_slug}"
        }
    ]
}

To monitor the progress of the job started above, send a GET request to the list/{listslug}/job/{jobslug}/ endpoint and monitor the 'pct_complete' field. Once this has reached 100, proceed to the next step.

View Changed Results

At this point, you only want to retrieve data for members that have changed. To retrieve a list of changed members, send a GET request to the member/{member_slug}/ endpoint and use the changed query parameter.

Command:

curl -X GET
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/member/?changed=true"

Sample output:

{
    "members": [
        {
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/ftL5TysJ/"
            }
        },
        {
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/wxM4337f/"
            }
        },
        {
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/HqghS1Cv/"
            }
        }
    ]
}

If you would like more detailed member output, add the '_expand' query parameter to your GET command.

Command:

curl -X GET
-H "Authorization: bearer {api_key}"
"https://api.datavalidation.com/1.0/list/{list_slug}/member/?changed=true&_expand=true"

Sample output:

{
    "members": [
        {
            "address": "oof@example.com",
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/ftL5TysJ/"
            },
            "slug": "ftL5TysJ",
            "tags": [],
            "changed": true
        },
        {
            "address": "rab@example.com",
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/wxM4337f/"
            },
            "slug": "wxM4337f",
            "tags": [],
            "changed": true
        },
        {
            "address": "bar@example.com",
            "meta": {
                "href": "https://api.datavalidation.com/1.0/list/NnKOdJUjjtdNhtQa/member/HqghS1Cv/"
            },
            "slug": "HqghS1Cv",
            "tags": [],
            "changed": true
        }
    ]
}

Automating Email Assurance

You should repeat this process weekly, or as frequently as necessary. You must run Email Assurance at least once every 30 days to keep your lists' subscribers active in our system.