List Guard

The List Guard service checks your email list for dead and toxic emails on a regular basis. You can either retrieve results from your InstantData account, or you can programmatically retrieve them as described here.

Retrieving the Most Recent Results

To get the most recent results from your List Guard account, use the endpoint

https://api.atdata.com/v5/listguard/results

Requests to this endpoint should include your List Guard API key in the api_key header as shown here:

curl --request GET \
     --url https://api.atdata.com/v5/listguard/results \
     --header 'api_key: <YOUR_API_KEY_HERE>'

This call will return the latest run results in CSV format, containing the following columns:

Email: The email address processed.
StatusCode: The status code indicates the result of the email validation.

Email,StatusCode
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400

The response does not include metadata such as the run date. If such details are necessary for your records, consider using the List of Recent Runs endpoint described below.

Retrieving a List of Recent Runs

To review recent runs and select a specific set of results, use the following API endpoint:

curl --request GET \
     --url https://api.atdata.com/v5/listguard \
     --header 'api_key: <YOUR_API_KEY_HERE>'

The response will return a list of recent runs with details such as the list_id, number of records processed, and the creation timestamp. You can use the list_id from these to retrieve runs from the desired list by calling the Results for a Specific List endpoint.

[
    {
        "list_id": 18899,
        "records": 106018,
        "created_at": "2024-06-11T16:50:39Z",
        "services": {
            "listguard": {
                "input_count": 106018,
                "completed_count": 106018,
                "reporting": {
                    "statuses": {
                        "Invalid": 77
                    }
                }
            }
        }
    },
    {
        "list_id": 18347,
        "records": 106465,
        "created_at": "2024-05-14T16:44:01Z",
        "services": {
            "listguard": {
                "input_count": 106465,
                "completed_count": 106465,
                "reporting": {
                    "statuses": {
                        "Invalid": 452
                    }
                }
            }
        }
    }
]

Retrieving Results for a Specific List

To obtain results for a specific run identified by list_id, use the following API endpoint:

curl --request GET \
     --url https://api.atdata.com/v5/list/<list_id>/results \
     --header 'api_key: <YOUR_API_KEY_HERE>'

This will return a CSV file similar to the response from the Most Recent Results endpoint, containing the validated emails and their status codes.

Email,StatusCode
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400
[email protected],400