API Documentation

Learn about the overall functionality of the MailerCheck API.

Email verification

Use MailerCheck API to check a single email address using real-time API or use bulk API methods to validate bigger lists.

Note: Single email address check and bulk email check required that your account has enough credits.

Check a single email and get real-time response.

POST /check/single

Body example

{
    "email": "[email protected]"
}

Response example

HTTP 200
{
    "status": "valid"
}


Return all lists that belong to the current account.

GET /lists

Response example

HTTP 200
[
    {
        "id": 15,
        "account_id": 2,
        "user_id": 5,
        "name": "Big email list.txt",
        "source": "myComputer",
        "type": "text",
        "column": 1,
        "delimiter": ",",
        "header": 0,
        "valid_file": true,
        "count": 10,
        "verification_started": "2020-02-17 22:02:19",
        "verification_ended": "2020-02-17 22:02:29",
        "dbload_started": "2020-02-17 22:02:21",
        "dbload_ended": "2020-02-17 22:02:21",
        "check_started": "2020-02-17 22:02:21",
        "check_ended": "2020-02-17 22:02:29",
        "credback_started": "2020-02-17 22:02:29",
        "credback_ended": null,
        "output_started": null,
        "output_ended": null,
        "created_at": "2020-02-17 22:02:14",
        "updated_at": "2020-02-17 22:02:29",
        "deleted_at": null,
        "encoding": null,
        "encoding_confidence": null,
        "integration_id": null,
        "header_row": "[\"Email\"]",
        "status": {
            "name": "done"
        },
        "statistics": {
            "syntax_error": 0,
            "typo": 0,
            "disposable": 0,
            "spamtrap": 0,
            "abuse": 0,
            "catch_all": 0,
            "mailbox_not_found": 0,
            "valid": 10,
            "unknown": 0,
            "mailbox_full": 0
        }
    },
    {
        "id": 16,
        "account_id": 2,
        "user_id": 5,
        "name": "Big list",
        "source": "mailerLite",
        "type": "text",
        ...
    }
]


Return a list with the specified ID.

GET /lists/{id}

Response example

HTTP 200
{
        "id": 15,
        "account_id": 2,
        "user_id": 5,
        "name": "Big email list.txt",
        "source": "myComputer",
        "type": "text",
        "column": 1,
        "delimiter": ",",
        "header": 0,
        "valid_file": true,
        "count": 10,
        "verification_started": "2020-02-17 22:02:19",
        "verification_ended": "2020-02-17 22:02:29",
        "dbload_started": "2020-02-17 22:02:21",
        "dbload_ended": "2020-02-17 22:02:21",
        "check_started": "2020-02-17 22:02:21",
        "check_ended": "2020-02-17 22:02:29",
        "credback_started": "2020-02-17 22:02:29",
        "credback_ended": null,
        "output_started": null,
        "output_ended": null,
        "created_at": "2020-02-17 22:02:14",
        "updated_at": "2020-02-17 22:02:29",
        "deleted_at": null,
        "encoding": null,
        "encoding_confidence": null,
        "integration_id": null,
        "header_row": "[\"Email\"]",
        "status": {
            "name": "done"
        },
        "statistics": {
            "syntax_error": 0,
            "typo": 0,
            "disposable": 0,
            "spamtrap": 0,
            "abuse": 0,
            "catch_all": 0,
            "mailbox_not_found": 0,
            "valid": 10,
            "unknown": 0,
            "mailbox_full": 0
        }
    }


Create a list with the specified name and emails.

POST /lists

Body example

{
    "name": "API List",
    "emails": [
        "[email protected]",
        "[email protected]",
    ]
}

Response example

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


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

POST /lists/upload

Body example

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

Response example

HTTP 201
{
    "source": "apiUpload",
    "name": "file.csv",
    "type": "text",
    "account_id": 1033,
    "user_id": 1026,
    "updated_at": "2020-02-28 13:19:07",
    "created_at": "2020-02-28 13:19:06",
    "id": 3042,
    "encoding": "us-ascii",
    "delimiter": ",",
    "column": 1,
    "header": 0,
    "count": 10,
    "header_row": "[\"Email\"]",
    "status": {
        "name": "not_started",
        "count": 10
    },
    "statistics": {
        "syntax_error": 0,
        "typo": 0,
        "disposable": 0,
        "catch_all": 0,
        "mailbox_not_found": 0,
        "valid": 0,
        "unknown": 0,
        "mailbox_full": 0
    }
}


Delete the list with the specified ID.

DELETE /lists/{id}

Response example

HTTP 204


Start verification for the specified list.

GET /lists/{id}/verify

Response example

HTTP 202
{
    "id": 32,
    "account_id": 2,
    "user_id": 5,
    "name": "API List 3",
    "source": "apiDirect",
    "type": "direct",
    "column": null,
    "delimiter": null,
    "header": null,
    "valid_file": null,
    "count": null,
    "verification_started": "2020-03-04 17:50:06",
    "verification_ended": null,
    "dbload_started": null,
    "dbload_ended": null,
    "check_started": null,
    "check_ended": null,
    "credback_started": null,
    "credback_ended": null,
    "output_started": null,
    "output_ended": null,
    "created_at": "2020-03-04 17:49:57",
    "updated_at": "2020-03-04 17:50:06",
    "deleted_at": null,
    "encoding": null,
    "encoding_confidence": null,
    "integration_id": null,
    "header_row": null,
    "status": {
        "name": "processing",
        "count": null
    },
    "statistics": {
        "syntax_error": 0,
        "typo": 0,
        "disposable": 0,
        "spamtrap": 0,
        "abuse": 0,
        "catch_all": 0,
        "mailbox_not_found": 0,
        "valid": 0,
        "unknown": 0,
        "mailbox_full": 0
    },
    "user": {
        "id": 5,
        "name": "[email protected]",
        "last_name": null,
        "email": "[email protected]",
        "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"
    }
}

Possible errors

Verification already started.

HTTP 409
{
    "error": "Verification already started"
}

Not enough credits to verify list.

HTTP 402
{
    "error": "Not enough credits. Credits required: 1"
}


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

GET /lists/{id}/results

Parameters

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).


Request example

/lists/28/results?limit=3&page=1&result=valid

Response example

HTTP 200
{
    "total": 10,
    "page": "1",
    "limit": "3",
    "has_more_pages": true,
    "last_page": 4,
    "result": "valid",
    "emails": [
        {
            "id": 75363,
            "account_id": 2,
            "email_list_id": 28,
            "address": "[email protected]",
            "line": 0,
            "checked": 1,
            "result": "valid",
            "created_at": null,
            "updated_at": "2020-02-20 19:28:53",
            "started": "2020-02-20 19:28:51",
            "our_finished": "2020-02-20 19:28:52",
            "remote_finished": "2020-02-20 19:28:53",
            "source_row": "[\"[email protected]\"]"
        },
        {
            "id": 75364,
            ...
        },
        {
            "id": 75365,
            ...
        }
    ]
}