Usage Guidelines
Please be sure to review our usage guidelines for the bulk API here.
The jobs create endpoint allows you create verify multiple emails together, the same way you would verify lists in the dashboard. This endpoint will create a job and process the emails in the list (if auto_start is enabled) asynchronously. Verification results are not returned in the response. Read more about how to verify lists of emails here.
Auto Parse
This will enable or disable the indexing process from automatically starting as soon as you create a job. If set to 0 or false you will need to call the /parse endpoint after the job has been created to begin indexing. Defaults to 0
Auto Start
This will enable or disable the job from automatically beginning the verification process once it has been parsed. If this is set to 0 or false you will need to call the /start endpoint to begin verification. Setting this to 1 or true will start the job and deduct the credits. Defaults to 0
Run Sample
This 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 endpoint. Read more about running a sample here. Defaults to 0
Input & Input Location
This endpoint can receive input in multiple ways. The input_location parameter describes the contents of the input parameter. The input parameter may be an array of objects containing emails or a file hosted at a remote URI.
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 authentication mechanisms. When using a URL that requires authentication be sure to pass the username and password in the URI string.
# Basic url
http://example.com/full/path/to/file.csv
# HTTP Basic Auth
http://name:[email protected]/full/path/to/file.csv
# FTP with authentication
ftp://name:[email protected]:21/full/path/to/file.csv
id,email,name
"12345","[email protected]","Fred McValid"
"12346","[email protected]","Bob McInvalid"
Supplied Data
Supplying the data directly gives you the option to dynamically create email lists on the fly rather than having to write to a file. input will accept an array of objects or arrays that contain the email, as well as any ancillary data you wish to associate with the email (e.g. user IDs, names, contact information).
If the data is supplied as an object, the key names will be used for the column headers. If the data is supplied as an array, column headers will be ommitted. Below is a sample of what each looks like in JSON.
[
{
"id": 12345,
"email": "[email protected]",
"name": "Fred McValid"
},
{
"id": 12346,
"email": "[email protected]",
"name": "Bob McInvalid"
}
]
[
[
12345,
"[email protected]",
"Fred McValid"
],
[
12346,
"[email protected]",
"Bob McInvalid"
]
]