Email Information Endpoint

On this page, we’ll dive into the email information endpoint you can use to retrieve information about any email address in order to verify & validate it.

curl -G https://api.emailvalidation.io/v1/info \
    -d email=support@emailvalidation.io \
    -H "apikey: YOUR-API-KEY"

{
    "email": "support@emailvalidation.io",
    "user": "support",
    "tag": "",
    "domain": "emailvalidation.io",
    "smtp_check": true,
    "mx_found": true,
    "did_you_mean": "",
    "role": true,
    "disposable": false,
    "score": 0.64,
    "state": "deliverable",
    "reason": "low_quality",
    "free": false,
    "format_valid": true,
    "catch_all": null,
    "catch_all_resolution": null,
    "bounce_probability": null,
    "status": "valid",
    "sub_status": "role_based",
    "explanation": "The mailbox exists, but it is a role address (such as info@ or support@), usually read by a team rather than one person.",
    "recommended_action": "send_with_caution"
}

Status / Recommended Action

The quickest way to decide what to do with an address. status says what the result means for sending, sub_status says why, and recommended_action says what to do. explanation is one fixed English sentence per sub_status that you can show to people.

{
    ...
    "status": "valid",
    "sub_status": "role_based",
    "explanation": "The mailbox exists, but it is a role address (such as info@ or support@), usually read by a team rather than one person.",
    "recommended_action": "send_with_caution"
}

sub_status is null for a plain valid result. Decide on status, sub_status and recommended_action, not on the explanation text, which is meant for people. See Result Statuses for every sub_status, its explanation and how the fields relate to state and reason.

State / Reason

The state is the deliverability and the reason is the reason why it is in this state. status and sub_status are derived from the same check and give a finer breakdown.

{
    ...
    "state": "deliverable",
    "reason": "valid_mailbox",
    ...
}

Possible states/reasons

User / Tag / Domain

These fields provide you with a simple way to look at the singular parts of an email address

{
    ...
    "user": "support",
    "tag": "mytag",
    "domain": "emailvalidation.io",
    ...
}

MX Check

The Simple Mail Transfer Protocol (SMTP), which is the very same protocol we all use to move emails on and across networks, is used by the emailvalidation.io API to verify email addresses.

By determining whether the requested domain is set up to accept email, our system starts the process of real-time email verification. Here is where the MX record check in the API is useful. The mx_found field of the API response tells you whether MX records were found for the domain.

{
    ...
    "mx_found": true,
    ...
}

"Did you mean" Check

In the "did you mean" object of the API result set, the emailvalidation.io API will propose a different email address if a potential misspelling or mistake in the requested email address's domain portion is identified.

Please be aware that the email address in the did you mean object is just a recommendation and has no bearing on the other API response objects.

{
    ...
    "did_you_mean": "support@emailvalidation.io",
    ...
}

Catch-All Detection

One SMTP check is not the end of the real-time verification procedure used by the emailvalidation.io API. A catch-all detection mechanism has been created since many email servers are set up to catch (accept) all incoming mail traffic, independent of the local component of the requested email address.

The catch-all check runs in the same connection to the mail server as the mailbox check, whenever the mail server accepts the address. It always runs, so setting the catch_all parameter does not make the request slower. To get its result in the catch_all field, add the catch_all parameter to your request and set it to 1.

Depending on whether the requested email address is discovered to be a part of a catch-all mailbox, the catch_all field in the API response will be true or false. It is also false when the check could not give a clear answer, and for large consumer email providers such as Gmail or Outlook.com, which check every mailbox themselves and are not probed.

An address on a catch-all domain that the mail server did not reject is returned with the state deliverable, the reason low_deliverability and the status catch_all (sub_status accept_all), whether or not you set the catch_all parameter and on every plan.

{
    ...
    "catch_all": true,
    ...
}

Catch-all resolution

For a catch-all domain the mailbox itself cannot be confirmed by one SMTP check, so the result carries a catch_all_resolution object describing how far we could get without ever sending an email. For any other result it is null.

{
    ...
    "status": "catch_all",
    "catch_all_resolution": {
        "method": "signals",
        "verdict": "unresolved",
        "evidence": ["mx_provider:google", "domain_cache"]
    },
    "bounce_probability": null
}

verdict is unresolved today: a true catch-all mailbox cannot be confirmed without sending to it, which we never do, so the object instead carries domain-level evidence (such as the mail provider family) you can weigh in a send decision. evidence never contains an address. The verdict may gain valid or invalid for domains we can resolve by other means; treat a value you do not know like unresolved.

bounce_probability is an estimated 0-to-1 chance that mail to the address bounces. It is null for now; a calibrated value is being developed and will keep the same meaning. Both fields are additive — existing fields are unchanged.

Disposable Check

If the requested email address is discovered to be utilizing a disposable email service like mailinator.com or trashmail.com, the API will also return a disposable JSON object with the values true or false.

{
    ...
    "disposable": true,
    ...
}

Services for Disposable Emails

A disposable email service enables users to anonymously create temporary email identities that are often used only once for tasks like activating accounts or getting passwords and expire after a set amount of time. Many of these email services don't require users to register, therefore the inbox of these one-time email accounts is made available to the public. We strongly advise against adding these email addresses to your recipient list.

Free Email Provider Check

The emailvalidation.io API can recognize free email services like Gmail, GMX or Yahoo since it is connected to a regularly updated database that lists all available email providers.

The free JSON object in the API response will either return true or false depending on whether the given email address is discovered to be utilizing a free service.

{
    ...
    "free": true,
    ...
}

Even while free email addresses are typically included in recipient lists, it might make sense for some email campaigns to separate them out and only deliver to addresses with a specific domain.

Role Check

Determining whether the requested email address is a role email address is another step in the emailvalidation.io email verification procedure. A role email is an address that often refers to a function rather than a person or name (for example, "support" or "postmaster"). Due to the low open rates of this sort of email address, it could occasionally be undesirable when sending email campaigns.

Example: If the requested email is a role address, the role JSON object in the API response will return true; otherwise, it will return false.

{
    ...
    "role": true,
    ...
}

Quality Score

The API returns a numeric Quality Score that sums up the other checks in one number. It is a fixed formula, the same for every address, not a prediction learned from past results.

{
    ...
    "score": 0.64,
    ...
}

The score starts at 0 and adds 0.16 for each of these:

• the mail server accepted the address or showed that the mailbox exists (smtp_check is true)
• the address is not disposable (a disposable address subtracts 0.32 instead)
• the address is not at a free email provider
• the address is not a role address
• there is no "did you mean" suggestion (a suggestion subtracts 0.32 instead)

The score never goes below 0, so it is always one of 0, 0.16, 0.32, 0.48, 0.64 or 0.80. An address with an invalid format, and an address we could not check because our validation service could not be reached, score 0.