# Account (/account)



## Account details [#account-details]

Returns the account associated with the token being used.

```http
GET https://app.mailercheck.com/api/account
```

### Response example [#response-example]

```json
{
    "id": 1033,
    "name": "John Doe's Company",
    "created_at": "2020-02-10 15:34:54",
    "updated_at": "2020-02-28 13:21:23",
    "deleted_at": null,
    "credits": 430408,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address": "123 nw",
    "city": "some city",
    "country": "somewhere",
    "postal_code": null,
    "region": null,
    "vat": null,
    "registration": null,
    "currency": null
}
```

## Get user [#get-user]

Returns the user associated with the token being used.

```http
GET https://app.mailercheck.com/api/user
```

### Response example [#response-example-1]

```json
{
    "id": 5,
    "name": "John Doe",
    "last_name": null,
    "email": "john@example.com",
    "email_verified_at": null,
    "subscribed_newsletter": 1,
    "avatar": null,
    "created_at": "2020-02-15 04:34:31",
    "updated_at": "2020-02-15 04:34:31",
    "terms_accepted_at": "2020-02-15 04:34:31"
}
```

## Credit balance [#credit-balance]

Get the amount of credits the account associated with the token has.

```http
GET https://app.mailercheck.com/api/credits
```

### Response example [#response-example-2]

```json
{
    "total": 999949
}
```


# Authentication (/authentication)



You authenticate using a bearer token. This token can be created through the MailerCheck UI by clicking on your profile picture and selecting "API", then clicking the "Create token" button. Give your token a name and that's it.

<Callout type="warn" title="Remember">
  Make sure to download or copy your token. You will not be able to see it again after you close the dialog.
</Callout>

## Authentication header [#authentication-header]

Once you have your token, you must include it in an Authorization header with each request you make to the API.

```bash
curl --location --request GET 'https://app.mailercheck.com/api/lists' \
--header 'Authorization: Bearer [your token]'
```

Your token is tied to the user that created it, and the account to which it was created under. All the endpoints will use this information and return the proper data.


# Email verification (/email)



## Single email verification [#single-email-verification]

Check a single email and get real-time response.

```http
POST https://app.mailercheck.com/api/check/single
```

### Request body example [#request-body-example]

```json
{
    "email": "example@example.com"
}
```

### Response example [#response-example]

HTTP 200

```json
{
    "status": "valid"
}
```

## Single email verification (Async) [#single-email-verification-async]

Check a single email and receive the result asynchronously to avoid delays and timeouts.

```http
POST https://app.mailercheck.com/api/check/single-async
```

### Request body example [#request-body-example-1]

```json
{
    "email": "example@example.com"
}
```

### Response example [#response-example-1]

HTTP 200

```json
{
    "id": "kvD8ezOq1OowB3jg",
    "state": "queued",
    "errors": null,
    "result": null
}
```

## Get single email result (Async) [#get-single-email-result-async]

Retrieve single email check result.

```http
GET https://app.mailercheck.com/api/check/single-async/{verification_id}
```

### Response example [#response-example-2]

HTTP 200

```json
{
  "id": "kvD8ezOq1OowB3jg",
  "state": "completed",
  "errors": null,
  "result": "typo"
}
```

## Get all lists [#get-all-lists]

Return all lists that belong to the current account.

```http
GET https://app.mailercheck.com/api/lists
```

### Parameters [#parameters]

| Parameter | Explanation                                    |
| --------- | ---------------------------------------------- |
| limit     | How many emails to show per page. Default 100. |
| page      | Which page to show. Default 1.                 |

### Response example [#response-example-3]

HTTP 200

```json
{
    "data": [
        {
            "id": 15,
            "account_id": 2,
            "user_id": 5,
            "name": "Big email list.txt",
            "source": "myComputer",
            "type": "text",
            "count": 10,
            "verification_started": "2020-02-17 22:02:21",
            "verification_ended": "2020-02-17 22:02:29",
            "created_at": "2020-02-17 22:02:14",
            "updated_at": "2020-02-17 22:02:29",
            "status": {
                "name": "done"
            },
            "statistics": {
                "valid": 0,
                "syntax_error": 0,
                "typo": 0,
                "mailbox_not_found": 0,
                "catch_all": 0,
                "mailbox_full": 0,
                "disposable": 0,
                "role": 0,
                "blocked": 0,
                "error": 0,
                "unknown": 0
            }
        },
        {
            "id": 16,
            "account_id": 2,
            "user_id": 5,
            "name": "Big list",
            "source": "mailerLite",
            "type": "text",
            ...
        }
    ],
    "links": {
        "first": "{url to first page}",
        "last": "{url to last page}",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "{url to next page}",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "{url to current page}",
        "per_page": 15,
        "to": 1,
        "total": 2
    }
}
```

## Get list [#get-list]

Return a list with the specified ID.

```http
GET https://app.mailercheck.com/api/lists/{id}
```

### Response example [#response-example-4]

HTTP 200

```json
{
    "id": 15,
    "account_id": 2,
    "user_id": 5,
    "name": "Big email list.txt",
    "source": "myComputer",
    "type": "text",
    "count": 10,
    "verification_started": "2020-02-17 22:02:21",
    "verification_ended": "2020-02-17 22:02:29",
    "created_at": "2020-02-17 22:02:14",
    "updated_at": "2020-02-17 22:02:29",
    "status": {
      "name": "done"
    },
    "statistics": {
        "valid": 0,
        "syntax_error": 0,
        "typo": 0,
        "mailbox_not_found": 0,
        "catch_all": 0,
        "mailbox_full": 0,
        "disposable": 0,
        "role": 0,
        "blocked": 0,
        "error": 0,
        "unknown": 0
    }
}
```

## Create list [#create-list]

Create a list with the specified name and emails.

```http
POST https://app.mailercheck.com/api/lists
```

### Request body example [#request-body-example-2]

```json
{
    "name": "API List",
    "emails": [
        "example@example.com",
        "example2@example.com"
    ]
}
```

### Response example [#response-example-5]

HTTP 201

```json
{
    "id": 33,
    "account_id": 2,
    "user_id": 5,
    "source": "apiDirect",
    "name": "API List",
    "type": "direct",
    "count": 10,
    "updated_at": "2020-03-04 18:11:07",
    "created_at": "2020-03-04 18:11:07",
    "status": {
      "name": "not_started",
      "count": null
    },
    "statistics": {
        "valid": 0,
        "syntax_error": 0,
        "typo": 0,
        "mailbox_not_found": 0,
        "catch_all": 0,
        "mailbox_full": 0,
        "disposable": 0,
        "role": 0,
        "blocked": 0,
        "error": 0,
        "unknown": 0
    }
}
```

## Upload list [#upload-list]

Create a list from an uploaded file (CSV or TXT).

```http
POST https://app.mailercheck.com/api/lists/upload
```

### Request body example [#request-body-example-3]

```bash
curl --location --request POST 'https://app.mailercheck.com/api/lists/upload' \
--header 'Authorization: Bearer [your token]' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------097290781055740441988275' \
--form 'file=@/Path/to/file.csv'
```

### Response example [#response-example-6]

HTTP 201

```json
{
    "id": 3042,
    "account_id": 1033,
    "user_id": 1026,
    "name": "file.csv",
    "source": "apiUpload",
    "type": "text",
    "count": 10,
    "updated_at": "2020-02-28 13:19:07",
    "created_at": "2020-02-28 13:19:06",
    "status": {
        "name": "not_started",
        "count": 10
    },
    "statistics": {
        "valid": 0,
        "syntax_error": 0,
        "typo": 0,
        "mailbox_not_found": 0,
        "catch_all": 0,
        "mailbox_full": 0,
        "disposable": 0,
        "role": 0,
        "blocked": 0,
        "error": 0,
        "unknown": 0
    }
}
```

## Delete list [#delete-list]

Delete the list with the specified ID.

```http
DELETE https://app.mailercheck.com/api/lists/{id}
```

### Response example [#response-example-7]

HTTP 204

## List verification [#list-verification]

Start verification for the specified list.

```http
PUT https://app.mailercheck.com/api/lists/{id}/verify
```

### Response example [#response-example-8]

HTTP 202

```json
{
    "id": 32,
    "account_id": 2,
    "user_id": 5,
    "name": "API List 3",
    "source": "apiDirect",
    "type": "direct",
    "count": 10,
    "verification_started": "2020-03-04 17:50:06",
    "verification_ended": null,
    "created_at": "2020-03-04 17:49:57",
    "updated_at": "2020-03-04 17:50:06",
    "status": {
        "name": "processing",
        "count": 10
    },
    "statistics": {
        "valid": 0,
        "syntax_error": 0,
        "typo": 0,
        "mailbox_not_found": 0,
        "catch_all": 0,
        "mailbox_full": 0,
        "disposable": 0,
        "role": 0,
        "blocked": 0,
        "error": 0,
        "unknown": 0
    }
}
```

### Possible errors [#possible-errors]

#### Verification already started [#verification-already-started]

HTTP 409

```json
{
    "error": "Verification already started"
}
```

#### Not enough credits to verify list [#not-enough-credits-to-verify-list]

HTTP 402

```json
{
    "error": "Not enough credits. Credits required: 1"
}
```

## Get list result [#get-list-result]

Get the individual emails from the list with the checking result.

```http
GET https://app.mailercheck.com/api/lists/{id}/results
```

### Parameters [#parameters-1]

| Parameter | Explanation                                                  |
| --------- | ------------------------------------------------------------ |
| limit     | How many emails to show per page. Default 100.               |
| page      | Which page to show. Default 1.                               |
| result    | Which type of emails you want to see. (valid, unknown, etc). |

### Response example [#response-example-9]

HTTP 200

```json
{
    "total": 10,
    "page": "1",
    "limit": "3",
    "has_more_pages": true,
    "last_page": 4,
    "result": "valid",
    "emails": [
        {
            "id": 75363,
            "address": "someone@example.com",
            "line": 0,
            "checked": 1,
            "result": "valid",
            "created_at": null,
            "updated_at": "2020-02-20 19:28:53"
        },
        {
            "id": 75364,
            ...
        },
        {
            "id": 75365,
            ...
        }
    ]
}
```

## Verification results [#verification-results]

The possible outcome of an email validation can be grouped in 3 categories: **Send to**, **Risky** and **Do not send to**.

| Category       | Result              | Explanation                                                                                                                 |
| -------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Send to        | valid               | The email is safe to send.                                                                                                  |
| Risky          | catch\_all          | Recipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person. |
| Risky          | mailbox\_full       | Recipient’s inbox is full and may not be able to receive new emails.                                                        |
| Risky          | role                | Email is role-based and may not be associated with a single, specific person but a group of people.                         |
| Risky          | unknown             | We are unable to determine if the email is valid or not valid.                                                              |
| Do not send to | syntax\_error       | The email is not valid.                                                                                                     |
| Do not send to | typo                | The email address has a typo. Correct the email address and retest.                                                         |
| Do not send to | mailbox\_not\_found | Recipient’s inbox does not exist.                                                                                           |
| Do not send to | disposable          | The email address is a temporary inbox and should be removed from your lists.                                               |
| Do not send to | blocked             | The email address’ mailbox is blocked by its service provider due to poor sending practices.                                |
| Error          | error               | There was an error while processing this email.                                                                             |


# What is MailerCheck? (/)



MailerCheck is an email verification, analysis and list cleaning tool for people who want to optimize their email list and improve email deliverability.

MailerCheck works with all major email marketing tools to improve email deliverability by detecting errors, bounces, catch-all domains, full inboxes and more.

## MailerCheck API [#mailercheck-api]

MailerCheck API is RESTful, fully-featured, and easy to integrate with.

You can use your favorite HTTP/REST library that is available for your programming language to make HTTP calls.

## Base URL [#base-url]

All API requests should start with the following base part:

```
https://app.mailercheck.com/api
```

<Callout type="info" title="Note">
  It's important to use HTTPS, otherwise you might experience unexpected results.
</Callout>

## Authentication [#authentication]

Authentication is done by adding an Authorization header to your API request that contains an API token.

In order to use the API token, it needs to be added as Authorization header with the contents of the header being Bearer XXX where XXX is your API token.

This token can be created through the MailerCheck UI by clicking on your profile picture and selecting "API" then click the "Create token" button, give your token a name and that's it.

```
Authorization: Bearer XXX
```

<Callout type="info" title="Note">
  Make sure to download or copy your token. You will not be able to see it again after you close the dialog.
</Callout>

Your token is tied to the user that created it, and the account to which it was created under. All the endpoints will use this information and return the proper data.

## API Versions [#api-versions]

Any breaking changes made to the API are released as dated, new versions. The current version is `2022-10-01`.

By default, all requests made to the MailerCheck API use the latest version, unless the `X-Version` header is present in the request.
To lock down the API version used in your integration, you can provide the current date at the time of your implementation through the `X-Version` header.

```
X-Version: 2022-10-01
```

## API response [#api-response]

MailerCheck follows the REST architectural style for it's API and conforms to generic HTTP response standards.

### HTTP response codes [#http-response-codes]

MailerCheck returns standard HTTP response codes.

| Code | Name                  | Explanation                                                                                                                                                |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | The request was accepted.                                                                                                                                  |
| 201  | Created               | Resource was created.                                                                                                                                      |
| 202  | Accepted              | The request was accepted and further actions are taken in the background.                                                                                  |
| 204  | No Content            | The request was accepted and there is no content to return.                                                                                                |
| 400  | Bad Request           | There was an error when processing your request. Please adjust your request based on the endpoint requirements and try again.                              |
| 401  | Unauthorized          | The provided API token is invalid.                                                                                                                         |
| 403  | Forbidden             | The action is denied for that account or a particular API token. Please make sure your account is allowed API access and check your API token permissions. |
| 404  | Not Found             | The requested resource does not exist on the system.                                                                                                       |
| 405  | Method Not Allowed    | HTTP method is not supported by the requested endpoint.                                                                                                    |
| 408  | Request Timeout       | There is an error on our system. [Please contact support](https://www.mailercheck.com/support)                                                             |
| 422  | Unprocessable Entity  | There was a validation error found when processing the request. Please adjust it based on the endpoint requirements and try again.                         |
| 429  | Too Many Requests     | There were too many requests made to the API. Read more on [rate limits](#rate-limits).                                                                    |
| 500  | Internal Server Error | There was an error on our system. [Please contact support](https://www.mailercheck.com/support)                                                            |
| 502  | Bad Gateway           | There was an error on our system. [Please contact support](https://www.mailercheck.com/support)                                                            |
| 503  | Service Unavailable   | There was an error on our system. [Please contact support](https://www.mailercheck.com/support)                                                            |
| 504  | Gateway Timeout       | There was an error on our system. [Please contact support](https://www.mailercheck.com/support)                                                            |

## Rate limits [#rate-limits]

MailerCheck has a default rate limit of 60 requests per minute on all API endpoints. If you exceed that rate limit, you will receive a 429 error response with a “Too Many Attempts.” message. Please wait for the amount of seconds indicated by `retry-after` and try again.

| Request type     | Rate limit         |
| ---------------- | ------------------ |
| All API requests | 60 requests/minute |

#### Example response [#example-response]

```http
HTTP/2 429
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
retry-after: 9
x-ratelimit-reset: 1696324073

{
    "message": "Too Many Attempts."
}
```

***

We try to keep our documentation clear and as simple as possible. If you have something you’d like to see, your [feedback](https://www.mailercheck.com/support) is always encouraged.