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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.acychecker.com/api-documentation/api-check-a-batch-of-emails.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.