The whole process of validating the list is divided into 2 steps:
Adding the list
Running the list for validation
There are two options to add the list of emails for list cleaning:
send an array of emails to the API
import as a CSV file
To send as an array of emails, use the API https://api-doc.emailconsul.com/post-listcleaning-list with the body containing the title, emails and profile_id(optional) fields, as
To import as a CSV file,
Firstly, send a GET request to get a presigned URL (see https://api-doc.emailconsul.com/get-listcleaning-list-import-presigned-url). In the response, you will get the url and the key fields.
Then use the url from the response to upload the CSV file to.
NOTE: the CSV file must contain the column email
After the file is successfully uploaded, use the API https://api-doc.emailconsul.com/post-listcleaning-list with the body containing the title, key and profile_id(optional) fields, as
Once the list is added, then preprocessing validation is automatically started in the background, which results in populating the following fields: invalid_format_count, duplicates_count, domains_count, emails_count (see the fields description below).
Once the preprocessing is done, the list status is set to PRE_PROCESSING_DONE, and the list is ready for validation.
To run the list for validation, use the API https://api-doc.emailconsul.com/post-listcleaning-list-run. Right after the run process is initiated, the status changes to PROCESSING.
NOTES:
You can start validation only if the status equals PRE_PROCESSING_DONE
It is unable to stop validation after the run process is initiated
Related credits for the list are frozen once the run process is initiated
It is unable to delete the list after the run process is initiated or completed
You can check the progress:
by getting the Listcleaning item from the GET request: https://api-doc.emailconsul.com/get-listcleaning-list-by-id
by getting the Listcleaning item from the webhook updates if you provided a webhook_url when creating the list.
While the validation is in progress, the status is PROCESSING. To see how many emails have already been processed, you can rely on listcleaning_results.count field, when emails_count indicates how many emails overall in the list. All other fields in the listcleaning_results reflect the aggregated results of validation process. Keep in mind that until validation is in progress (status equals PROCESSING), the data in listcleaning_results is intermediate.
Once the validation process is completed and the list status becomes DONE, you can retrieve the results in one of the following ways:
Get raw results
Export results as CSV (streamed response)
Get a presigned URL to download a prepared CSV file
To get raw data, use the API https://api-doc.emailconsul.com/get-listcleaning-list-by-id
To export results as CSV, use the API https://api-doc.emailconsul.com/get-listcleaning-list-export
To get presigned URL, use the API https://api-doc.emailconsul.com/get-listcleaning-list-presigned-url
This option requires both conditions:
List status must be DONE
The list must contain available CSV variants in the field available_presaved_lists
Allowed key values: all, safe-to-send, send-with-caution
A presigned URL is valid for 1 hour.
To delete the list, use API https://api-doc.emailconsul.com/delete-listcleaning-list-by-id
NOTE: it is forbidden to remove the list if it is already sent for validation.
To get all lists, use the API https://api-doc.emailconsul.com/get-listcleaning-lists
{string} id - Unique identifier of the document
{string} title - Title of the list
{string} profile_id - The profile ID that the list is attached to
{string} status - Current status of the document
Available options:
INIT - when the list is created
PRE_PROCESSING - when pre-processing is started and in progress
PRE_PROCESSING_DONE - when pre-processing is completed
PROCESSING - when processing (validation) is started
DONE - when validation is completed
FAILED - when pre-processing or processing is failed for any reason. See preprocessing_error or processing_error field for the error message
{array} available_presaved_lists - Available pre-saved CSV variants generated after the validation is completed
Available options:
all - full CSV file with all validated email addresses
safe-to-send - CSV file containing emails only with deliverable status
send-with-caution- CSV file containing risky or unknown emails
{string} key - Unique key identifier, available only if the list has been added through a presigned url link
{number} emails_count - Total number of emails in the list
{number} invalid_format_count - Number of emails with invalid format. Available after pre-processing is done
{number} duplicates_count - Number of duplicate emails found. Available after pre-processing is done
{number} domains_count - Number of unique domains. Available after pre-processing is done
{Date} created_at - Timestamp when a list was created
{Date} updated_at - Timestamp of last list update
{Date} processing_start_at - Timestamp when processing started
{Date} processing_end_at - Timestamp when processing completed
{string | null} preprocessing_error - Error message if pre-processing failed
{string | null} processing_error - Error message if processing failed
{object} listcleaning_results - list cleaning validation results
{number} listcleaning_results.count - Total number of email addresses processed
{number} listcleaning_results.deliverable - Number of email addresses that are considered deliverable
{number} listcleaning_results.risky - Number of email addresses that are considered risky to send to
{number} listcleaning_results.undeliverable - Number of email addresses that are undeliverable
{number} listcleaning_results.unknown - Number of email addresses with unknown status
{number} listcleaning_results.toxicity_0 - Count of addresses with toxicity level 0 (lowest)
{number} listcleaning_results.toxicity_1 - Count of addresses with toxicity level 1
{number} listcleaning_results.toxicity_2 - Count of addresses with toxicity level 2
{number} listcleaning_results.toxicity_3 - Count of addresses with toxicity level 3
{number} listcleaning_results.toxicity_4 - Count of addresses with toxicity level 4
{number} listcleaning_results.toxicity_5 - Count of addresses with toxicity level 5 (highest)
{string} email - The email address being validated
{string} status - The validation status of the email
Available options: deliverable, risky, undeliverable, unknown
{string} reason - The reason for the validation result
Available options: accepted_email, low_deliverability, low_quality, invalid_email, invalid_domain, rejected_email, dns_error, unavailable_smtp, unsupported, timeout, unknown
{object} domain - Domain-related information
{string} domain.name - The domain name
{string} domain.accept_all - Whether the domain accepts all emails
Available options: yes, no, unknown
{string} domain.disposable - Whether the domain is disposable
Available options: yes, no, unknown
{string} domain.free - Whether the domain is free
Available options: yes, no, unknown
{object} account - Account-related information
{string} account.role - Whether a generic address is assigned to a role or group, such as info@ or support@
Available options: yes, no, unknown
{string} account.disabled - Whether the account is disabled
Available options: yes, no, unknown
{string} account.full_mailbox - Whether the mailbox is full
Available options: yes, no, unknown
{object} dns - DNS-related information
{string} dns.type - The type of DNS record
{string} dns.record - The DNS record value
{string} provider - The email provider name
{number} score - The validation score
Range: 0 ≤ x ≤ 100
{string} toxic - Whether the email is considered toxic
{number} toxicity - The toxicity score (0-5)
Range: 0 ≤ x ≤ 5
The List Cleaning API sends webhook notifications to the configured webhook URL whenever the list status or related data changes during the cleaning process. These notifications allow you to track different stages of list processing, including preprocessing completion, cleaning progress updates, and presaved list generation.
This webhook notification is sent when the preprocessing stage of the uploaded list has finished. At this stage the system validates the uploaded data and calculates initial statistics.
{string} id- Unique identifier of the listcleaning list
{string} title - Title of the list
{string} profile_id - The profile ID that the list is attached to
{string} status- Current status of the listcleaning preprocessing process
Available options:
PRE_PROCESSING_DONE- when the list is preprocessed and ready to be cleaned
FAILED- when the list preprocessing failed
{string} key - Unique key identifier, available only if the list has been added through a presigned url link
{string} emails_count- Total number of emails in the list
{string} invalid_format_count- Number of emails with invalid format
{string} duplicates_count- Number of duplicate emails found
{string} domains_count- Number of unique domains in the list
{Date} created_at- Timestamp when a list was created
{Date} updated_at- Timestamp of last list update
{string | null} preprocessing_error- Error message if pre-processing failed
This webhook notification is sent during the list cleaning process whenever the list status or results are updated. This notification may be triggered multiple times while the list status is PROCESSING. Each event contains the current aggregated results of the cleaning process at that moment
{string} id- Unique identifier of the listcleaning list
{string} title - Title of the list
{string} profile_id - The profile ID that the list is attached to
{string} status- Current status of the listcleaning preprocessing process
Available options:
PROCESSING- when the list is being processed
DONE- when validation is completed and list is ready to download. But presaved list will be available later
FAILED- when processing is failed for any reason. See processing_error field for the error message
{string} key - Unique key identifier, available only if the list has been added through a presigned url link
{string} emails_count- Total number of emails in the list
{string} invalid_format_count- Number of emails with invalid format
{string} duplicates_count- Number of duplicate emails found
{string} domains_count- Number of unique domains in the list
{Date} created_at- Timestamp when a list was created
{Date} updated_at- Timestamp of last list update
{Date} processing_start_at- Timestamp when processing started
{Date} processing_end_at- Timestamp when processing completed
{string | null} preprocessing_error- Error message if pre-processing failed
{string | null} processing_error- Error message if processing failed
{object} listcleaning_results - list cleaning validation results
{number} listcleaning_results.count - Total number of email addresses processed
{number} listcleaning_results.deliverable - Number of email addresses that are considered deliverable
{number} listcleaning_results.risky - Number of email addresses that are considered risky to send to
{number} listcleaning_results.undeliverable - Number of email addresses that are undeliverable
{number} listcleaning_results.unknown - Number of email addresses with unknown status
{number} listcleaning_results.toxicity_0 - Count of addresses with toxicity level 0 (lowest)
{number} listcleaning_results.toxicity_1 - Count of addresses with toxicity level 1
{number} listcleaning_results.toxicity_2 - Count of addresses with toxicity level 2
{number} listcleaning_results.toxicity_3 - Count of addresses with toxicity level 3
{number} listcleaning_results.toxicity_4 - Count of addresses with toxicity level 4
{number} listcleaning_results.toxicity_5 - Count of addresses with toxicity level 5 (highest)
This webhook notification is sent whenever a presaved lists becomes available to download.
{string} id- Unique identifier of the listcleaning list
{array} available_presaved_lists - Available pre-saved CSV variants generated after the validation is completed
Available options:
all - full CSV file with all validated email addresses
safe-to-send - CSV file containing emails only with deliverable status
send-with-caution- CSV file containing risky or unknown emails
For large email lists, we strongly recommend using the Import as CSV file instead of sending large arrays of emails directly in the request body.
Uploading lists via CSV is significantly faster and more reliable, especially for lists containing tens or hundreds of thousands of emails.
The typical workflow looks like this:
Get a presigned upload URL
Convert your email list into a CSV file or using exist
Upload the CSV file using the presigned URL
Create a list using the returned key
NOTE: The CSV file must contain a header named email.
The following example demonstrates how to convert an array of emails into a CSV file and upload it using the Import CSV API:
For large lists, we recommend downloading results using the presigned URL instead of requesting results directly from the API response. This approach allows you to retrieve the full dataset as a CSV file in a single request and parse it on the fly.
Using presigned URLs provides several advantages:
Speed - CSV downloads are significantly faster for large lists
Reliability - avoids large API responses and potential timeouts
Scalability - works efficiently even for very large lists
Before downloading the results, your system should wait for the webhook notification indicating that the desired presaved list is available. Once the webhook contains the required list variant (all, safe_to_send or send_with_caution), you can immediately download it using the presigned URL.
The following example demonstrates how to request a presigned URL, download the CSV file, and parse it into JSON:
Emails that can be used free of charge:
Any of them can be modified with a ”+” suffix to generate more unique emails. For example:
NOTE: The credits for the sandbox emails return back AFTER the validation process is complete, so you can use them over and over again.