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

← Account