The List Guard service works by regularly checking your Monitoring File of email addresses for dead and toxic emails.

You can update your Monitoring File in three ways:

1. By using SafeToSend.
2. By using the InstantData client portal.
3. By using the List API.

Add to your Monitoring File by using SafeToSend

Most of our List Guard customers also use SafeToSend for validating new email addresses. Your SafeToSend account can be configured to automatically add all valid email addresses to your List Guard Monitoring File. Just let us know, and we'll be happy to set it up!

Update your Monitoring File using the InstantData client portal

After logging into InstantData, click on the API tab, then find your List Guard API key.

In the Actions menu, you may chose an option to add emails to your Monitoring File, or remove emails from it.

Both options will prompt you for a file of email addresses. Simply select the file, and you're done!

📘

Important

Updates may take up to 24 hours to post to your account, so please allow extra time before your next List Guard Run Date.

Update your Monitoring File using the List API

You can also submit files to add to and delete from your Monitoring File via the List API, which is recommended for automated processing. You can submit as many files as you need per day.

The first step is to find your List Guard API key, which is required for all List API requests. Log into InstantData, go to the API tab, and find your API key.

The following is an example of using the List API to upload a file to be added to your Monitoring File:

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

This request accepts the following query parameters:

• type: Should be set to monitoring, indicating that you are updating your List Guard Monitoring file.
• action: Indicates whether the file is for adding or deleting records. Possible values are add or delete.
• email=1: Specifies the column position of the email addresses in your file.
• 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 email addresses.
• The header parameter is optional and can be set to true or false.

🚧

List Guard Key

Remember to replace <YOUR_API_KEY_HERE> with your actual List Guard Key. And for the status request below, replace <YOUR_LIST_ID> with the List ID returned when you posted the file.

Retrieving the List ID and Checking the Status:

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

{
  "list_id": <List ID>,
  "size_bytes": 9999
}

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

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

This will return a JSON similar to the following:

{
  "list_id": <List ID>,
  "name": "LOAD_FILE.csv",
  "status": "Results",
  "records": 100,
  "size_bytes": 9999,
  "created_at": "2025-04-13T17:21:01Z"
}

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

📘

Important

Even after you receive a status of "Results" from your upload, the actual update may take up to 24 hours to post to your account, so please allow extra time before your next List Guard Run Date.