# AcyChecker documentation

Documentation for AcyChecker API and Plugin (WordPress & Joomla)

### The extensions for WordPress and Joomla

* [Dashboard](/acychecker/dashboard)
* [Clean my database](/acychecker/clean-my-database)
* [Block on registration](/acychecker/block-on-registration)
* [Tests listing](/acychecker/test-listing)
* [Configuration](/acychecker/configuration)

### The API

* [Get remaining credits](/api-documentation/api-get-remaining-credits)
* [Check an email address](/api-documentation/api-single-email-check)
* [Check email addresses in bulk](/api-documentation/api-check-a-batch-of-emails)


# AcyChecker Plugin WordPress & Joomla

This is the documentation about the AcyChecker plugin on Joomla and WordPress

AcyChecker is a plugin that allows you to connect to the AcyChecker API to test the reliability of your subscribers' email addresses.

With this plugin you'll be able to block your user depending on the API response, here is the list of what the API detects:

* **If an email is disposable**: A disposable email address is temporary, it's convenient for people who don't want to give their real email address on any website. For your email marketing it isn't great because you send emails to non-existing users.
* **If an email is registered on a free domain**: This means that the email address creation was free, like Gmail or Yahoo for example. There are no cons on your side if you want to send marketing emails to them.
* **If a domain is an accept all**: This means that all email addresses on that domain will work, you'll be able to send emails to them but there are potentially no one receiving them.
* **If the domain doesn't exist**: This means that the domain doesn't exist and therefore the email address doesn't exist either. It isn't recommended to send emails to email addresses that don't exist because it impacts your IP reputation and you can be considered more easily as a spammer.
* **If it's a role-based email address**: Role-based email addresses are ones that do not belong to a specific user, but more to a role. For example, <support@example.com> is a role-based email address.
* **If it doesn't exist on the SMTP server**: This means that we asked via [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) protocol if we can send an email to this email address, and it responded that the address doesn't exist. Like the non-existing domains, it is bad for your IP reputation to send emails to a non-existing receiver.

The domain of an email address is what follows the @ sign, for example **acyba.com** in **<example@acyba.com>**.


# Dashboard

Documentation about the AcyChecker plugin's dashboard

### Information

In this first part, you'll have some information about the number of users subscribed during the last month/year.\
When you don't have any license key set, there is information about how many fake users you have. Please note that percentage is only tested on a sample of your users, we do not perform all the tests.

![](/files/w8XGBo9PIIKsUyZZ5LGu)

The first button **Clean my database** redirects you to the configuration page [Clean my database](/acychecker/clean-my-database) while **Block fake users registration** redirects you to the configuration page [Block on registration](/acychecker/block-on-registration).

### Statistics

<figure><img src="/files/pZJWSXXAgL7TtEmLt2TL" alt=""><figcaption></figcaption></figure>

You'll find here a summary of the email addresses tested.


# Clean my database

Documentation page for the configuration page Clean my database on the AcyChecker plugin

This configuration page allows you to check all the users on your website and block them based on the conditions you've selected.

![](/files/PWzwLMIstTvMD5ofV5on)

### Choose which users to test

<figure><img src="/files/4q8TwFcj0ffr9yEPfsJM" alt=""><figcaption></figcaption></figure>

This first part allows you to select which users you want to test. For now, you can test your website users and AcyMailing users.

You can also refine the users to test by filtering them by user group or subscribed lists.

### What to do with the bad users?

<figure><img src="/files/2f7AJtzdYEL1id3IfuiD" alt=""><figcaption></figcaption></figure>

When checking users in bulk, you can choose to automatically block the ones that meet the criteria you select below.\
You can also choose to decide later. In this case, you will be able to see the results and decide what to do on the **Tests** menu by clicking the ["Handle test results"](/acychecker/test-listing#handle-test-results) button.

### On which criteria should the users be blocked?

<figure><img src="/files/5AUt0nUUdoPxB3xIAegP" alt=""><figcaption></figcaption></figure>

This part lets you choose the conditions to find the bad users on your website. The users will be blocked if they match **at least one** of the selected conditions.

* **Is a disposable email address**: A disposable email address is temporary, it's convenient for people who don't want to give their real email address on any website. For your email marketing it isn't great because you send emails to non-existing users.
* **Is an accept all email address**: This means that all email addresses on that domain will work, you'll be able to send emails to them but there are potentially no one receiving them.
* **Is registered through a free domain**: This means that the email address creation was free, like Gmail or Yahoo for example. There are no cons on your side if you want to send marketing emails to them.
* **Is a role based email address**: Role-based email addresses are ones that do not belong to a specific user, but more to a role. For example, <support@example.com> is a role-based email address.
* **Is registered through a non-existent domain**: This means that the domain doesn't exist and therefore the email address doesn't exist either. It isn't recommended to send emails to email addresses that don't exist because it impacts your IP reputation and you can be considered more easily as a spammer.
* **Does not exist on the SMTP server of the domain**: This means that we asked via [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) protocol if we can send an email to this email address, and it responded that the address doesn't exist. Like the non-existing domains, it is bad for your IP reputation to send emails to a non-existing receiver.

### When should AcyChecker test your users?

<figure><img src="/files/Lo889E0z1CVcsWXFApdS" alt=""><figcaption></figcaption></figure>

You can either test all your user base once (select **Right now**), or set up AcyChecker to regularly check your users (select **Every week** or **Every month**).

You can disable the weekly/monthly tests by clicking the **Stop periodic tests** button.

{% hint style="info" %}
When using the "Right now" option, your users are added in the queue that can be seen in the **Tests** menu. You can expect to receive 5000 test results every 6 minutes on average.
{% endhint %}


# Block on registration

Documentation page for the configuration page Block on registration on the AcyChecker plugin

In this configuration, you can set to check for users' email address reliability before they register or subscribes.

![](/files/HTIOKaOvU4NHngzBsf4K)

### Which users should be tested?

In the first part, you can select which registration process you want to protect. In this example, AcyChecker will verify users before they can create a new account on the website or subscribe to an AcyMailing list.

### On which criteria should we prevent the users from registering/subscribing?

In the second part, you can select which types of email addresses are not accepted:

* **Is a disposable email address**: A disposable email address is temporary, it's convenient for people who don't want to give their real email address on any website. For your email marketing it isn't great because you send emails to non-existing users.
* **Is an accept all email address**: This means that all email addresses on that domain will work, you'll be able to send emails to them but there are potentially no one receiving them.
* **Is registered through a free domain**: This means that the email address creation was free, like Gmail or Yahoo for example. There are no cons on your side if you want to send marketing emails to them.
* **Is a role based email address**: Role-based email addresses are ones that do not belong to a specific user, but more to a role. For example, <support@example.com> is a role-based email address.
* **Is registered through a non-existent domain**: This means that the domain doesn't exist and therefore the email address doesn't exist either. It isn't recommended to send emails to email addresses that don't exist because it impacts your IP reputation and you can be considered more easily as a spammer.
* **Does not exist on the SMTP server of the domain**: This means that we asked via [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) protocol if we can send an email to this email address, and it responded that the address doesn't exist. Like the non-existing domains, it is bad for your IP reputation to send emails to a non-existing receiver.


# Tests

Documentation page for the Tests menu on the AcyChecker plugin

On this page, you will be able to check all the tested email addresses and their results.

![](/files/gUHF6inqkEHLJ64DyczJ)

### Action buttons

<figure><img src="/files/aOUkhE78VzqGr9g8waNs" alt=""><figcaption></figcaption></figure>

* **Cancel pending tests:** Clicking this button will remove the email addresses from the testing queue if they have the "Pending" status. You cannot cancel tests for the ones with "In progress" status because they are already being tested by our service.
* **Clear finished tests:** This will delete test results for tests with the "Finished" status.
* **Export:**
  * **Export test results:** This will download a file with all the tests matching the current filters (search and status). Checking rows on the listing prior to clicking the export button has no effect.
  * **Export blocked users:** This will download a file with the email address, date and reason for all the users that have been blocked based on your configuration.
  * **Export deleted users:** This will download a file with the email address, date and reason for all the users that have been deleted based on your configuration.
* **Handle test results:** You can mass block/delete users based on some conditions with this action. You can also select users on the listing before clicking the button to make sure conditions only apply on the selected users.

### Listing

* **Email**: The email address tested
* **Name**: The name of the user that has been tested
* **User status**: It shows if AcyChecker blocked/removed this user based on your configuration. If it did, a red cross will be shown with a tooltip showing the reason
* **Date**: The date when the test has been sent
* **Trustworthiness**: This result isn't taken into account when blocking/deleting fake users. It is calculated based on the results you can see in other columns.
* **Domain exists**: Whether the domain of the email address exists.
* **Disposable**: If the email address is disposable
* **Accept all**: If the domain accepts all incoming emails even if the recipient doesn't exist.
* **Role email**: If the email belongs to a role instead of someone, <support@example.com> is a role based email address.
* **Free**: If the email address was created using a free service, like Gmail for example.
* **Current step:** A test can be **Pending** (either waiting for available credits or for the previous batch to finish), **In progress** (sent to our API and waiting to receive the results), **Finished** (results received), **Failed** (didn't receive the results)
* **Actions**: You can manually unblock/block/delete users with these actions

For the trustworthiness column, here are the possible values:

* **Not existing**: We are sure that this email address doesn't exist, either because the domain doesn't exist or we contacted its domain and it told us that the address didn't exist
* **Risky**: If it is a disposable email address, if we couldn't connect to the domain or if the domain answered with a non-conventional return code
* **Possible**: If the domain exists but refused to answer, or if it's an "accept all" domain
* **Valid**: This is a real email address that is not an accept all domain

### Handle test results

When cleaning your database, you have the option to either automatically block users based on your conditions, or first run a test on the email addresses then decide what to do afterwards.

In the later case, clicking the **Handle test results** button on this page will open this popup:

<figure><img src="/files/bsVfJvNa6HivUdlmZlrM" alt=""><figcaption></figcaption></figure>

You will find the same options as in the [**Clean my database**](/acychecker/clean-my-database) menu, and a preview with the number of users matching the selected conditions will be shown at the bottom. Note that users that are already blocked will still count in this preview.


# Configuration

This is the main configuration page of the AcyChecker extension. Activate and monitor AcyChecker here.

<figure><img src="/files/3aCgmWELol3hGgjKoMoh" alt=""><figcaption></figcaption></figure>

### Global configuration

* **License key:** On this page, this option lets you enter your license key to activate your license.\
  Once logged in on our website, you'll find your license keys on your account page: <https://www.acychecker.com/my-account/license/>
* **Whitelist addresses ending with:** This option lets you automatically consider email addresses as correct based on their domain (even if they should match the conditions you selected for bad users). Separate patterns with a comma. You can enter:
  * a specific domain like "@example.com"
  * a country extension like ".co.uk"
  * a regular expression such as "@hotmail.(com|net|fr)$"
* **Blacklist addresses:** This option lets you automatically consider email addresses as bad based on their domain. Separate patterns with a comma. You can enter:
  * a specific domain like "@example.com"
  * a country extension like ".co.uk"
  * a regular expression such as "@hotmail.(com|net|fr)$"
* **Blacklist names containing**: In addition to email addresses, AcyChecker can test the names of users. Some spam users could for example add URLs or promote spam activities in their name, in case they are displayed somewhere on websites.\
  Separate banned words with a comma.\
  If you want to add a regular expression, please start it with the beginning character "^" and the ending character "$".
* **Blacklist names longer than**: You can set a limit on the length for user names. Users with names longer than the specified value will be blocked.\
  Keep the value to 0 if you want to disable this option.&#x20;

### Logs

This part lets you see and delete the logs collected by AcyChecker when an error occurs. Errors could occur during three main actions.

### Maintenance

When migrating your website to an other server or if an update goes wrong, some information may be missing in the AcyChecker tables in your database.

If this happens, clicking the **Check database integrity** button will automatically fix any issue on AcyChecker tables (missing tables, missing columns, missing primary key, etc...)


# Get remaining credits

## Get remaining credits

<mark style="color:blue;">`GET`</mark> `https://api.acychecker.com/api/v1/licenses/credits`

This endpoint allows you to get the remaining monthly credits for the specified license.&#x20;

#### Headers

| Name                                           | Type   | Description                                                                  |
| ---------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| API-KEY<mark style="color:red;">\*</mark>      | string | The API key linked to the license you want to get the remaining credits from |
| Content-Type<mark style="color:red;">\*</mark> | string | Must be "application/json"                                                   |
| Source<mark style="color:red;">\*</mark>       | string | The name of your app, "my app" for example.                                  |

{% tabs %}
{% tab title="200 When you provided a correct API key." %}

```
{
    "message": "",
    "credits_used_batch": 335,
    "remaining_credits_batch": 665
    "credits_used_simple": 11,
    "remaining_credits_simple": 39
}
```

{% endtab %}

{% tab title="401 When the API key provided doesn't exist, or if the license is expired." %}

```
{
    "message": "Invalid API-KEY"
}

OR

{
    "message": "License expired"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}


# Check a single email address

## Single email check

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

This endpoint allows you to test an email address and get the results.&#x20;

#### Path Parameters

| Name                                    | Type   | Description                         |
| --------------------------------------- | ------ | ----------------------------------- |
| email<mark style="color:red;">\*</mark> | string | The email address you want to check |

#### Headers

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

{% tabs %}
{% tab title="200 The check results are returned in a data element." %}

```
{
    "message": "",
    "data": {
        "email": "email@example.com",
        "valid": true,
        "disposable": false,
        "free": true,
        "role": false,
        "d_exists": true,
        "exists": "valid",
        "accept_all": false
    }
}
```

{% endtab %}

{% tab title="401 When the API key provided doesn't exist, or if the license is expired." %}

```
{
    "message": "Invalid API-KEY"
}

OR

{
    "message": "License expired"
}
```

{% endtab %}

{% tab title="403 When you exceeded the monthly credits for the provided API key." %}

```
{
    "message": "No credits left",
    "data": []
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}


# Check a batch of email addresses

You can either check your email addresses with an JSON input or a CSV input&#x20;

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