Everything Location - /email/batch
This endpoint provides the ability to upload and process a list of email addresses in CSV format. Please note that files uploaded using an evaluation API key are limited to 1,000 records.
Note: only old everythinglocation keys will work with this service.
Resource URL
https://api.everythinglocation.com/email/batch
Note: we don't support API connections using HTTP - all calls should use HTTPS.
Resource Information
| Preferred method | POST |
| Requires authentication? | Yes, valid API key |
| Chargeable? | Yes |
1) POST /email/batch
Upload the file containing the email address data and create the batch task ID.
Format: Input file must use CSV file extension, although file values may be either comma separated or tab delimited.
Headers: A column header is required on the first line. The header for the input email address data must be labelled ‘email’.
Request Parameters
| Name | Descrition |
|---|---|
| lqtkey Required |
A valid license key with sufficient credit available to process the requested batch task. Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| email Required |
The name attribute for the FILE input field must be set to ‘email’. Sample HTML is enclosed below. |
Response Parameters
| Status | The result of your call. "OK" indicates success, any other status indicates an error. Example: "Status":"OK" |
| email_batch[] | An array containing confirmation plus additional data relating to the batch task:
Sample JSON output[] is enclosed below. |
Example Request
<form method="POST" enctype="multipart/form-data" action="https://api.everythinglocation.com/email/batch ?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI"> <input type="file" name="email" /> </form>
Example Response (JSON)
{
"Status":"OK",
"email_batch":[
{
"job_id":"d88389fa7ec8f3514a8…11189324582016-03-25",
"submitted_file":"email-batch-job-1.csv",
"estm_total_trans":5000,
"start_time":"2016-03-25 19:00:59"
}
]
}
2) GET /email/batch
Retrieve a list of all email batch tasks associated to an API key.
Request Parameters
| Name | Descrition |
|---|---|
| lqtkey Required |
A valid license key with sufficient credit available to process the requested batch task. Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
Response Parameters
| Status | The result of your call. "OK" indicates success, any other status indicates an error. Example: "Status":"OK" |
| batch_jobs[] | An array of information relating to email batch tasks. Each item will contain:
Sample JSON output[] is enclosed below. |
Example Request
GET https://api.everythinglocation.com/email/batch ?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI
Example Response (JSON)
{
"Status":"OK",
"batch_jobs":{
"result":[
{
"job_id":"d88389fa7ec8f3514a8…11189324582016-03-25",
"status":"downloaded",
"progress":"100%"
},
{
"job_id":"9012a08fbb0242aa6e5…ff63efa0b12016-03-27",
"status":"complete",
"progress":"100%"
},
{
"job_id":"543d47a27c80d57f402…e4d394afa22016-03-27",
"status":"verifying",
"progress":"67%"
}
]
}
}
3) GET /email/batch/<job_id>
Retrieve detailed information for a single batch task.
Request Parameters
| Name | Descrition |
|---|---|
| lqtkey Required |
A valid license key with sufficient credit available to process the requested batch task. Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| job_id Required |
A valid batch task ID. Example: 543d47a27c80d57f402…e4d394afa22016-03-27 |
Response Parameters
| Status | The result of your call. "OK" indicates success, any other status indicates an error. Example: "Status":"OK" |
| batch_status[] | An array of information relating to the requested batch task. The structure of the response can be defined in two ways and is determined by the status field of the task. The following fields are always returned:
Pre-download (status does not equal ‘downloaded’)
Post-download (status equals ‘downloaded’)
Sample JSON output[] is enclosed below. |
Example Request
GET https://api.everythinglocation.com/email/batch /ace9b72550065075637512c5adddc656c037e6387e2016-03-25 ?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI
Example Response #1: "status" ≠ "downloaded" (JSON)
{
"Status":"OK",
"batch_status":{
"job_id":"d88389fa7ec8f3514a8…11189324582016-03-25",
"submitted_file":"email-batch-job-1.csv",
"start_time":"2016-03-25 19:00:59",
"progress":"45%",
"status":"verifying",
"estm_total_trans":5000,
"estm_credit_cost":25000
}
}
Example Response #2: "status" = "downloaded" (JSON)
{
"Status":"OK",
"batch_status":{
"job_id":"d88389fa7ec8f3514a8…11189324582016-03-25",
"submitted_file":"email-batch-job-1.csv",
"start_time":"2016-03-25 19:00:59",
"finish_time":"2016-03-25 19:00:59",
"progress":"100%",
"status":"downloaded",
"stats":{
"valid":4854,
"invalid":139,
"accept_all":5,
"unknown":2
},
"total_records":5000
"credit_cost":25000
}
}
4) GET /email/batch/<job_id>?download
Download the completed batch task from the server.
Request Parameters
| Name | Descrition |
|---|---|
| lqtkey Required |
A valid license key with sufficient credit available to process the requested batch task. Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| job_id Required |
A valid batch task ID. Example: 543d47a27c80d57f402…e4d394afa22016-03-27 |
| download Required |
Requests the file download. |
Request Parameters
The response will return the completed file to the browser or application using CSV file format. The file name
will be <job_id>_verified.csv.
Users receiving an error should next check the status of the batch task using GET /email/batch/<job_id>.
Example Request
GET https://api.everythinglocation.com/email/batch /ace9b72550065075637512c5adddc656c037e6387e2016-03-25 ?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI&download
