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.emailconsul.com/api/v1.0/doc/#/Listcleaning/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.emailconsul.com/api/v1.0/doc/#/Listcleaning/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.emailconsul.com/api/v1.0/doc/#/Listcleaning/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.dev.emailconsul.com/api/v1.0/doc/#/Listcleaning/post_listcleaning_list__id__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.emailconsul.com/api/v1.0/doc/#/Listcleaning/get_listcleaning_list__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 is completed (status equals DONE), then there are two options to get results:
Get the raw data with API https://api.emailconsul.com/api/v1.0/doc/#/Listcleaning/get_listcleaning_list__id__results
Export in CSV with API https://api.emailconsul.com/api/v1.0/doc/#/Listcleaning/get_listcleaning_list__id__export
To delete the list, use API https://api.emailconsul.com/api/v1.0/doc/#/Listcleaning/delete_listcleaning_list__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.emailconsul.com/api/v1.0/doc/#/Listcleaning/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 values:
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.
{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
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.