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
Please note that 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

​
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

NameDescription
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

NameDescription
StatusThe 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:
  • job_id [String]: a unique identifier for the task (52 characters)
  • submitted_file [String]: the name of the uploaded file
  • estm_total_trans [Integer]: number of email records in the imported file
  • start_time [Date]: Date/time that the batch task was created and submitted.
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"
      }
   ]
}

​
GET /email/batch

Retrieve a list of all email batch tasks associated to an API key.

​
Request Parameters

NameDescription
lqtkey (Required)A valid license key with sufficient credit available to process the requested batch task.

Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI

​
Response Parameters

NameDescription
StatusThe 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:
  • job_id [String]: the unique identifier for the task
  • status [String]:
  • pending – batch job has been queued
  • file_error – file could not be processed due to an error
  • loading – file preparation prior to processing
  • verifying – batch task in progress
  • complete – processed file is ready for download
  • downloaded – processed file has been downloaded and charged for
  • progress [String]: task completion, expressed as a percentage
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%"
         }
      ]
   }
}

​
GET /email/batch/<job_id>

Retrieve detailed information for a single batch task.

​
Request Parameters

NameDescription
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

NameDescription
StatusThe 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:
  • job_id [String]: the unique identifier for the task
  • submitted_file [String]: the name of the uploaded file
  • start_time [Date]: Date/time that the batch task was created
  • finish_time [Date]: Date/time that the batch task completed
  • progress [String]: task completion, expressed as a percentage
  • status [String]: pending, file_error, loading, verifying, complete, downloaded
Pre-download (status does not equal ‘downloaded’)
  • estm_total_trans [Integer]: number of email records in the imported file
  • estm_credit_cost [Decimal]: the estimated total charge for the batch task
Post-download (status equals ‘downloaded’)
  • stats [Array]:
  • total_trans [Integer]: total number of email addresses submitted
  • valid [Integer]: number of email records that were valid
  • invalid [Integer]: number of email records that were invalid
  • accept_all [Integer]: number of records that were accept-all addresses
  • unknown [Integer]: number of email records with unknown status
  • credit_cost [Decimal]: the final total charge for the batch task, in credits
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
   }
}

​
GET /email/batch/<job_id>?download

Download the completed batch task from the server.

​
Request Parameters

NameDescription
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