# Email verification

# Single email verification

Check a single email and get real-time response.

POST https://app.mailercheck.com/api/v1/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/v1/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",
        ...
    }
]

# Get list

Return a list with the specified ID.

GET https://app.mailercheck.com/api/v1/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 list

Create a list with the specified name and emails.

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

# Request body example

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

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

# Upload list

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

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

# Request 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 'file=@/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 list

Delete the list with the specified ID.

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

# Response example

HTTP 204

# List verification

Start verification for the specified list.

GET https://app.mailercheck.com/api/v1/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": "javier@mailerlite.com",
        "last_name": null,
        "email": "javier@mailerlite.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"
    }
}

# 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/v1//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,
            "account_id": 2,
            "email_list_id": 28,
            "address": "someone@example.com",
            "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": "[\"someone@example.com\"]"
        },
        {
            "id": 75364,
            ...
        },
        {
            "id": 75365,
            ...
        }
    ]
}

# Verification results

The possible outcome of an email validation.

Result Explanation
valid Email is safe to send.
syntax_error Email is not valid. Do not send to.
typo Email address has a typo. Correct email address and retest.
mailbox_not_found Recipient’s inbox does not exist. Do not send.
catch_all ERecipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person.
mailbox_full Recipient’s inbox is full and may not be able to receive new emails. Use caution when sending.
unknown We are unable to determine if the email is valid or not valid. Use caution when sending.
disposables These email addresses should be removed from your lists. These are temporary email addresses people use to avoid getting spam in their inbox.
Last updated: 2/12/2021, 12:37:18 PM