# Check a batch of email addresses

You can either check your email addresses with an JSON input or a CSV input 

## Check emails per batch with a CSV

<mark style="color:green;">`POST`</mark> `https://api.acychecker.com/api/v1/bulk_verify`

This endpoint allows you to test multiple email addresses. The results won't be returned right away.\
There are three methods to get the results:\
\- the results can be consulted on a specific page (this is always available, the URL is given to you when creating the batch)\
\- by email when the batch is tested (in this case you must provide a callback\_email)\
\- the results can be posted to an URL of your choice (in this case you must provide a callback\_url)\
\
The results are removed and cannot be recovered after one month.

#### Headers

| Name                                           | Type   | Description                                 |
| ---------------------------------------------- | ------ | ------------------------------------------- |
| API-KEY<mark style="color:red;">\*</mark>      | string | Your API key                                |
| Source<mark style="color:red;">\*</mark>       | string | The name of your app, "My app" for example. |
| Content-Type<mark style="color:red;">\*</mark> | string | multipart/form-data                         |

#### Request Body

| Name                                     | Type | Description                                                                    |
| ---------------------------------------- | ---- | ------------------------------------------------------------------------------ |
| emails<mark style="color:red;">\*</mark> | file | A CSV file without quotes, with all the email addresses to test (one per line) |

{% tabs %}
{% tab title="201: Created When the testing batch has been accepted by the API." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request When the version of the CMS integration plugin is too low" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden When you don't have enough credits OR when using an old version of our integration plugin" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity When you didn't provide any email address with the call." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="429: Too Many Requests When you've sent a lot of requests to our API in a short amount of time." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Check emails per batch with a JSON

<mark style="color:green;">`POST`</mark> `https://api.acychecker.com/api/v1/bulk_verify`

This endpoint allows you to test multiple email addresses. The results won't be returned right away.\
There are three methods to get the results:\
\- the results can be consulted on a specific page (this is always available, the URL is given to you when creating the batch)\
\- by email when the batch is tested (in this case you must provide a callback\_email)\
\- the results can be posted to an URL of your choice (in this case you must provide a callback\_url)\
\
The results are removed and cannot be recovered after one month.

#### Headers

| Name                                           | Type   | Description                                 |
| ---------------------------------------------- | ------ | ------------------------------------------- |
| API-KEY<mark style="color:red;">\*</mark>      | string | Your API key                                |
| Source<mark style="color:red;">\*</mark>       | string | The name of your app, "My app" for example. |
| Content-Type<mark style="color:red;">\*</mark> | string | application/json                            |

#### Request Body

| Name                                     | Type   | Description                                                                                                |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| fileType                                 | string | <p>The type of the export file, must be either JSON or <br>CSV, if nothing is set default is JSON</p>      |
| callbackEmail                            | string | An email address to which the results will be sent when the tests are finished                             |
| callbackUrl                              | string | An url called when the batch is finished                                                                   |
| emails<mark style="color:red;">\*</mark> | string | Must be a json encoded array of email addresses, for example:\["<john@example.com>", "<lola@example.com>"] |

{% tabs %}
{% tab title="201: Created When the testing batch has been accepted by the API." %}

```
{
    "test_id": 875,
    "url_result": "https://api.acychecker.com/api/v1/bulk_result/875"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity When you didn't provide any email address with the call." %}

```
{
    "message": "There are no emails in the list"
}
```

{% endtab %}

{% tab title="429: Too Many Requests When you've sent a lot of requests to our API in a short amount of time." %}

```
{
    "message": "Too many requests"
}
```

{% endtab %}

{% tab title="403: Forbidden When you don't have enough credits OR when using an old version of our integration plugin" %}

```javascript
{
    "message": "Not enough credits to do this batch"
}
```

{% endtab %}

{% tab title="400: Bad Request When the version of the CMS integration plugin is too low" %}

```javascript
{
    "message": "Could not process request, please verify that you use the latest version."
}
```

{% endtab %}
{% endtabs %}

## Get a list of your batches results

<mark style="color:blue;">`GET`</mark> `https://api.acychecker.com/api/v1/bulk_result/{id}`

#### Query Parameters

| Name                                 | Type    | Description                                  |
| ------------------------------------ | ------- | -------------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | The ID of the batch you want the results for |

#### Headers

| Name                                      | Type   | Description  |
| ----------------------------------------- | ------ | ------------ |
| API-KEY<mark style="color:red;">\*</mark> | string | Your API key |

{% tabs %}
{% tab title="200: OK When the results are ready or if tests are still calculating." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden When the API key you provided doesn't correspond to the one used to create the batch." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found No result found." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="429: Too Many Requests When you've sent a lot of requests to our API in a short amount of time." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get the batch's results

<mark style="color:blue;">`GET`</mark> `/api/v1/bulk_result/{id}`

No matter the method chosen to get the results (sent to an email, a callback URL, or manually), the results will always be available for one month.

#### Path Parameters

| Name                                 | Type    | Description                                    |
| ------------------------------------ | ------- | ---------------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | The ID given to you when you created the batch |

#### Headers

| Name                                      | Type   | Description  |
| ----------------------------------------- | ------ | ------------ |
| API-KEY<mark style="color:red;">\*</mark> | string | Your API key |

{% tabs %}
{% tab title="200: OK When the results are ready or if tests are still calculating." %}

```
{
    "message": "The test is still in progress. Currently handled 20 / 200",
    "data": [],
    "status": "in_progress",
    "tested_emails": 20,
    "total_emails": 200,
    "progress": "10%"
}

OR

{
    "message": "",
    "data": [
        "results": [
            {
                "email": "address1@example.com",
                "valid": true,
                "disposable": false,
                "free": false,
                "role": false,
                "d_exists": true,
                "suggestions": [],
                "exists": "valid",
                "accept_all": false
            },
            {
                "email": "address2@example.com",
                "valid": true,
                "disposable": false,
                "free": true,
                "role": false,
                "d_exists": true,
                "suggestions": [],
                "exists": "possible",
                "accept_all": true
            }
        ]
    ]
}
```

{% endtab %}

{% tab title="403: Forbidden When the API key you provided doesn't correspond to the one used to create the batch." %}

```
{
    "message": "You can't access this result",
    "data": []
}
```

{% endtab %}

{% tab title="404: Not Found When the result either doesn't exist yet / anymore, or if an error occurs internally when getting the results." %}

```
{
    "message": "No result found",
    "data": []
}

OR

{
    "message": "The content of the result can't be found.",
    "data": []
}
```

{% endtab %}

{% tab title="429: Too Many Requests When you've sent a lot of requests to our API in a short amount of time." %}

```
{
    "message": "Too many requests"
}
```

{% endtab %}
{% endtabs %}