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

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

Name	Description
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

Name	Description
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.

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

Name	Description
lqtkey (Required)	A valid license key with sufficient credit available to process the requested batch task. Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI

Response Parameters

Name	Description
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.

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

Name	Description
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

Name	Description
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.

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

Name	Description
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

Getting started

Endpoints

Everything Location - /email/batch

Resource Information

POST /email/batch

Request Parameters

Response Parameters

Example Request

Example Response (JSON)

GET /email/batch

Request Parameters

Response Parameters

Example Request

Example Response (JSON)

GET /email/batch/`<job_id>`

Request Parameters

Response Parameters

Example Request

Example Response #1: “status” ≠ “downloaded” (JSON)

Example Response #2: “status” = “downloaded” (JSON)

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

Request Parameters

Request Parameters

Example Request

​Resource Information

​POST /email/batch

​Request Parameters

​Response Parameters

​Example Request

​Example Response (JSON)

​GET /email/batch

​Request Parameters

​Response Parameters

​Example Request

​Example Response (JSON)

​GET /email/batch/<job_id>

​Request Parameters

​Response Parameters

​Example Request

​Example Response #1: “status” ≠ “downloaded” (JSON)

​Example Response #2: “status” = “downloaded” (JSON)

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

​Request Parameters

​Request Parameters

​Example Request

Resource Information

POST /email/batch

Request Parameters

Response Parameters

Example Request

Example Response (JSON)

GET /email/batch

Request Parameters

Response Parameters

Example Request

Example Response (JSON)

GET /email/batch/`<job_id>`

Request Parameters

Response Parameters

Example Request

Example Response #1: “status” ≠ “downloaded” (JSON)

Example Response #2: “status” = “downloaded” (JSON)

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

Request Parameters

Request Parameters

Example Request