> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Everything Location - /email/batch

> Please note that this is a legacy product in retirement

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](https://api.everythinglocation.com/email/batch)

<Note>Please note that we don't support API connections using HTTP - all calls should use HTTPS.</Note>

## 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. <br /><br />Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| email (Required)  | The name attribute for the FILE input field must be set to ‘email’. <br /><br />Sample HTML is enclosed below.                                          |

### Response Parameters

| Name            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status          | The result of your call. "OK" indicates success, any other status indicates an error. <br /><br />Example: "Status":"OK"                                                                                                                                                                                                                                                                                                                                     |
| email\_batch\[] | An array containing confirmation plus additional data relating to the batch task: <ul><li>job\_id \[String]: a unique identifier for the task (52 characters)</li><li>submitted\_file \[String]: the name of the uploaded file </li><li>estm\_total\_trans \[Integer]: number of email records in the imported file </li><li>start\_time \[Date]: Date/time that the batch task was created and submitted.</li></ul>Sample JSON output\[] is enclosed below. |

### Example Request

```JSON theme={null}
<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)

```JSON theme={null}
{
   "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. <br /><br />Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |

### Response Parameters

| Name           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Status         | The result of your call. "OK" indicates success, any other status indicates an error. <br /><br />Example: "Status":"OK"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| batch\_jobs\[] | An array of information relating to email batch tasks. Each item will contain: <ul><li>job\_id \[String]: the unique identifier for the task </li><li>status \[String]: </li><li>pending – batch job has been queued </li><li>file\_error – file could not be processed due to an error </li><li>loading – file preparation prior to processing </li><li>verifying – batch task in progress </li><li>complete – processed file is ready for download </li><li>downloaded – processed file has been downloaded and charged for </li><li>progress \[String]: task completion, expressed as a percentage</li></ul>Sample JSON output\[] is enclosed below. |

### Example Request

```JSON theme={null}
GET https://api.everythinglocation.com/email/batch
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI
```

### Example Response (JSON)

```JSON theme={null}
{
   "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. <br /><br />Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| job\_id (Required) | A valid batch task ID. <br /><br />Example: 543d47a27c80d57f402…e4d394afa22016-03-27                                                                    |

### Response Parameters

| Name             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Status           | The result of your call. "OK" indicates success, any other status indicates an error. <br /><br />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:<ul><li>job\_id \[String]: the unique identifier for the task</li><li>submitted\_file \[String]: the name of the uploaded file</li><li>start\_time \[Date]: Date/time that the batch task was created</li><li>finish\_time \[Date]: Date/time that the batch task completed</li><li>progress \[String]: task completion, expressed as a percentage</li><li>status \[String]: pending, file\_error, loading, verifying, complete, downloaded</li></ul>Pre-download (status does not equal ‘downloaded’)<ul><li>estm\_total\_trans \[Integer]: number of email records in the imported file</li><li>estm\_credit\_cost \[Decimal]: the estimated total charge for the batch task</li></ul>Post-download (status equals ‘downloaded’)<ul><li>stats \[Array]:</li><li>total\_trans \[Integer]: total number of email addresses submitted</li><li>valid \[Integer]: number of email records that were valid</li><li>invalid \[Integer]: number of email records that were invalid</li><li>accept\_all \[Integer]: number of records that were accept-all addresses</li><li>unknown \[Integer]: number of email records with unknown status</li><li>credit\_cost \[Decimal]: the final total charge for the batch task, in credits</li></ul>Sample JSON output\[] is enclosed below. |

### Example Request

```JSON theme={null}
GET https://api.everythinglocation.com/email/batch
/ace9b72550065075637512c5adddc656c037e6387e2016-03-25
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI
```

### Example Response #1: "status" ≠ "downloaded" (JSON)

```JSON theme={null}
{
   "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)

```JSON theme={null}
{
   "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. <br /><br />Example: BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI |
| job\_id (Required)  | A valid batch task ID. <br /><br />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

```JSON theme={null}
GET https://api.everythinglocation.com/email/batch
/ace9b72550065075637512c5adddc656c037e6387e2016-03-25
?lqtkey=BFtd2UpC8Gl1jU1pPnDZIVpoz2XnBMyWEfVcAfoI&download
```