The bulk endpoint provides high-speed validation on a list of email addresses. You can use the status endpoint to retrieve real-time statistics about a bulk job in progress. Once the job has finished, the results can be retrieved with our download endpoint. Read more about this workflow here.
When creating a new job, verification will begin automatically after it has been indexed.
Run Sample
The bulk endpoint has the ability to run a sample on the list and provide you with an estimated bounce rate without costing you. Based on the estimated bounce rate you can decide whether or not to perform the full validation or not. You can start validation by calling the start_job endpoint. Read more about running a sample here.
Input & Input Location
The bulk endpoint can receive input in multiple ways. The input_location parameter describes the contents of the input parameter. The input parameter may be a list of encoded email addresses, a file hosted at a remote URL, or other resource identifier based on the value of input_location. For now, two input_location styles are available. Remote URL and Supplied Data.
Remote URL
Using a remote URL allows you to host the file and provide us with a direct link to it. The file should be a list of emails separated by line breaks or a standard CSV file. We support most common file transfer protocols and their related authentication mechanisms. We suggest using either HTTP, HTTPS, FTP, FTPS or SFTP. When using a URL that requires authentication be sure to pass the username and password in the actual URL. When using SFTP keep in mind that we do not currently support key based authentication.
# Basic url
http://example.com/full/path/to/file
# HTTP Basic Auth
http://name:[email protected]/full/path/to/file
# FTP with authentication
ftp://name:[email protected]:21/full/path/to/file
Supplied Data
Supplying the data directly gives you the option to dynamically create email lists on the fly. input will accept a list of emails separated by line breaks or the data from a CSV file. When using this method be sure that you are properly encoding the data to ensure it has not become mangled.
Separating emails with
\n(or other newline representations) is not the same as separating them with newline characters. When it comes time to encode the list of emails the\nrepresentation will be encoded as the literal\andncharacters separately.