Bulk API List Submission Overview

Sending a file by URL

The URL submitted must lead directly to the file and contain the type of input used, as well as any authentication credentials the request needs. The URL should be sent in the request as the input parameter and the input_type should be set to url. Below is an example request:

Sending data directly

Data submitted directly should exist as an array of arrays or an array of objects. The data should be sent in the request as the input parameter and the input_type should be set to data. Below is an example of this request:

Request Response

When you submit a list via the API, the verification process will start automatically. If your credit balance is insufficient, the verification of your list will fail. You can purchase credits from the portal.

If an error occurs, the response will look like the below example:

The failure description may vary depending on the type of fail action. Examples of common failure messages are:

• Token invalid or does not exist
• The data format is wrong (when passing the data directly)

Once you receive a response, you will want to store the value of the token, as it will be used to check the status and eventually retrieve the results.

Checking the file status

Now that your list is running, you will need to poll the API and check the status periodically. For the first status check we recommended to wait approximately one minute until our cleaning system begins processing the file. For smaller lists (<50k) polling every 5-10 seconds is acceptable, but for larger lists (>50k) you’ll want to poll less frequently.

Request Status

In the response, the status parameter will indicate what the list is currently doing. Typically, status will be the only parameter you will need to watch. However, you may find the additional fields useful for monitoring list progress or to view a breakdown of the results in your list while it’s processing.

"status" : This top-level job progress field contains one of four possible conditions. Shown below are these possible conditions and associated descriptions.

• "TokenNotFound" - Token was not found in the system.
• "Fail" - The cleansing process has failed and cannot complete the process. Action to take: Review the submitted data and retry if it did not follow the data format. (Note: The message of this status may vary depending on the error.)
• "Queued" - The file is queued for pickup and job submission.
• "Pending" - The job is in the queue waiting for the process to start.
• "Running" - Your list has been imported and has begun the cleansing process. For additional job progress, follow the checkpoint field for additional detail.
• "Success" - Your list has completed and is ready for use. Action to take: Use pickup URL to download the results contained within a compressed file.

"checkpoint" : If you wish to follow the cleansing process in greater detail and the status condition = running then use the checkpoint field to determine job progress. Below are the possible condition descriptions.

• "Importing" - Cleansing job has started the import of your list.
• "Cleaning" - Cleansing job has imported your list and has begun the cleansing phase.
• "Classifying Results" - Classifying results and preparing report.
• "Cleansed" - Cleansing job has completed Classifying Results phase and will begin exporting results.
• "Exported" - Cleansing job results are ready for pickup.

Once the status value is set to success, you may begin retrieval of the results.

Retrieving the Results

Now with the cleansing process complete, it’s time to view our findings.

Downloading Results

The data will be returned in a zip file containing the results.

Example: SampleFileAPI.zip

The following export files contain the full row of fields initially provided in comma-delimited or CSV files unless noted otherwise:

	Cleaned. Once a file has completed processing, it will be placed in this folder as a compressed (zip) file of the same name as the original file.
		Within the compressed file you will find the following files and folders:
			SampleFileAPI-CERTIFIED.csv (20,000) All email addresses in this file have been certified good to send. You may upload this list to your ESP and send to each address with full confidence.
			SampleFileAPI-DISCRETIONARY.csv (0) We are able to conclude that these email addresses do not represent a threat to your online reputation, yet we are unable to conclusively verify that these addresses are deliverable. In order to provide to you additional detail and insight into the results obtained, we also include the following sub-classifications: Catch-All, Greylisted, Connection Timeout and Indeterminate. We advise sending this group initially on a separate network (domain/IP) to confirm bounce ratio is within acceptable norms before sending through your main sending network.
			SampleFileAPI-SUPPRESS.csv (10,000) All addresses in this file should be entirely removed from your active mailing list as they have been classified as “Do Not Email.” These addresses contain various reputation and deliverability threats and should be avoided. You may use this list as a suppression file to be uploaded to your ESP for ease of use. This export contains the following threat classifications: Trap, Mole, Quarantine, Seed (Bots/Role/Disposable/Seed/Dormant), Key, Parked, Invalid.
			SampleFileAPI-REPORT.html HTML File containing a link to this report (List Profile Report).

All file exports are formatted following the same field structure as provided with an additional field appended named “mxgroup” (Certified and Discretionary) or “threatclass” (Suppress). These file exports are sorted in ascending order (A-Z) using one of the two appended fields.

The “mxgroup” field identifies the domain/ organization responsible for handling the reception and acceptance or filtering of email for that particular email address. For more information, see Delivery Group section.

General Disclaimer: Every reasonable effort is made to locate all known threat and delivery classification elements mentioned herein, yet due to the constantly changing and dynamic nature of the online environment, we can not guarantee the results or deliverable will be free of any/all traps, threat or delivery classification elements identified within this report.

While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Impressionwise does not accept responsibility for any kind of loss resulting from the use of information provided.

Questions? Please feel free to reach out with any questions you may have about our cleansing process or your results, and we look forward to you experiencing the results that truly set Impressionwise apart!