# Email verification

# Single email verification

Check a single email and get real-time response.

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

# Request body example

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

# Response example

HTTP 200

{
    "status": "valid"
}

# Get all lists

Return all lists that belong to the current account.

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

# Parameters

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

# Response example

HTTP 200

{
    "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

Return a list with the specified ID.

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

# Response example

HTTP 200

{
    "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 a list with the specified name and emails.

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

# Request body example

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

# Response example

HTTP 201

{
    "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

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

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

# Request body example

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

HTTP 201

{
    "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 the list with the specified ID.

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

# Response example

HTTP 204

# List verification

Start verification for the specified list.

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

# Response example

HTTP 202

{
    "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

# 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 list result

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

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

# Parameters

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

HTTP 200

{
    "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

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.
Last updated: 10/16/2023, 7:55:42 AM