Loqate

Developer API  |  Everything Location  |  /email/batch

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

Resource Information

Preferred method POST
Requires authentication? Yes, valid API key
Chargeable? Yes

Back to top

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.

Back to top

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:
  • 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.

Back to top

Example Request


<form method="POST" enctype="multipart/form-data"
action="https://api.everythinglocation.com/email/batch
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI">
<input type="file" name="email" />
</form>

Back to top

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"
      }
   ]
}

Back to top

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

Back to top

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:
  • 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.

Back to top

Example Request


GET https://api.everythinglocation.com/email/batch
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI

Back to top

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%"
         }
      ]
   }
}

Back to top

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

Back to top

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:
  • 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.

Back to top

Example Request


GET https://api.everythinglocation.com/email/batch
/ace9b72550065075637512c5adddc656c037e6387e2016-03-25
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI

Back to top

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
   }
}

Back to top

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
   }
}

Back to top

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.

Back to top

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

Back to top

Take a trial - no obligation, full support Get started