NAV Navbar
shell javascript go python java

Real-Time API

Introduction

Real-Time API is a simple HTTP GET Request based RESTful API with JSON responses. This means that you can validate emails automatically without the app.correct.email interface.

You can use it to improve the safety of your forms or mobile applications as well as create automated checking of your inboxed emails and more.

Not A Developer?

If you are not a developer and simply want to check your email lists, we recommend using Email Checker. If you want to protect your forms against spam-traps, temporary emails and other harmful emails, then our Form Defender is your best choice.

Authentication

To get access to Correct.Email API you must firs create an Application. Every Application has unique API Key (UUID). The API Key is required in every request and must be given as a URL query parameter.

Renew API Key

API Keys can be changed for each Application. However, you should remember that all your previous references to the Application will not work anymore and will need to be adjusted.

HTTP Request

GET https://api.correct.email/v1/single/

Example requests

curl "https://api.correct.email/v1/single/?key=your_api_key&email=email_to_be_checked"
  fetch('https://api.correct.email/v1/single/?key=your_api_keyemail=email_to_be_checked')
    .then(resp => {
        // ... response
    })
    .catch(error => {
        // ... error
    });
  var query url.Values
  query.Add("key", "your_api_key")
  query.Add("email", "email_to_be_checked")
  query.Add("ip", "ip_of_request")

  url, _ := url.Parse("https://api.correct.email/v1/single/")
  url.RawQuery = query.Encode()

  resp, _ := http.Get(url.String())
from urllib.parse import urlencode
from urllib import request

query = (('key','your_api_key'),('email','email_to_be_checked'),('ip','ip_of_request'))
url = 'https://api.correct.email/v1/single/' + '?' + urlencode(query)
req = request.Request(url, method='GET')
resp = request.urlopen(req)
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.ProtocolException;
import java.net.URL;
import java.net.URLEncoder;

public class JavaGetRequest {

    private static HttpURLConnection con;

    public static void main(String[] args) throws MalformedURLException,
            ProtocolException, IOException {

        String url = ("https://api.correct.email/v1/single/");

        url += "?key=" + URLEncoder.encode("your_api_key", "UTF-8");
        url += "&email="+ URLEncoder.encode("email_to_be_checked", "UTF-8");
        url += "&ip="+ URLEncoder.encode("ip_of_request", "UTF-8");

        try {
            URL myurl = new URL(url);
            con = (HttpURLConnection) myurl.openConnection();

            con.setRequestMethod("GET");

            StringBuilder content;

            try (BufferedReader in = new BufferedReader(
                    new InputStreamReader(con.getInputStream()))) {

                String line;
                content = new StringBuilder();

                while ((line = in.readLine()) != null) {
                    content.append(line);
                    content.append(System.lineSeparator());
                }
            }

            System.out.println(content.toString());

        } finally {
            con.disconnect();
        }
    }
}

The above commands return JSON structured like this:

{
  "status": "success",
  "data": {
      "status": "temporary",
      "address": "test@example.com",
      "account": "test",
      "domain": "example.com",
      "anonymous": false,
      "tor": false,
      "spamIP": false,
      "blacklist": false,
      "duration": 0.121806599,
      "isSpammer": false
    }
}

URL Parameters

Parameter Required Description
key true API Key generated in your application at https://app.correct.email/en/api/.
email true The email address to be checked.
ip false Replace origin IP address

Data in response

Field Type Meaning
status string Email address status.
address string Checked email address.
mailbox string User of email address (before '@').
host string Hostname of email address (after '@').
anonymous boolean true when TOR, PROXY or VPN was used.
tor boolean true when TOR was used.
spamIP boolean true when IP is marked as spam IP.
spamEmail boolean true this email is marked as spammer.
blacklisted boolean true if address was added to blacklist.
duration float Time (in seconds) between sending request and getting response.

Email address statuses

Possible statuses of email address given in JSON response as data.status:

Email Address status placement

  {
    "status": "success",
    "data": {
      "status": "clean",
      ...
    }
  }
Status Meaning
“clean” Email address is ok.
“catch-all” Email address is forwarding to another location.
“special” Email address has a special or role-based function, ex. admin@gmail.com
“invalid” Record has invalid syntax.
“spam-trap” Email address luring spam without communication.
“bad-mx” Email address with non-existent or faulty domain.
“bounced” Fake email address that does not exist.
“temporary” Email address generated for a fixed period, often just 10 minutes.
“unknown” Email address where the status is unknown (very rare).

Learn more at Correct.email Knowledge Base - Email Statuses

Response statuses

Possible statuses in "status" key of JSON responses:

Status Meaning
"success" Email address has been checked successfully.
"error" There was an error while checking email address.

Error Response

Error response (JSON) is received in same structure for every request.

Example response

{
    "status": "error",
    "data": {
        "id": "app_key_invalid",
        "code": 1000
    },
    "message": "Invalid application key"
}
Error message ID Code Meaning
Application key is not valid app_key_invalid 1000 API key is invalid.
Your account is blocked. Contact support account_blocked 1001 Your account has been blocked. To get more information please contact via Support.
Rate limit has been exceeded live_rate_limit_reached 1002 Too many requests have been sent in a short period of time. These limits can be set in API.
Not enough credits for request not_enough_credits 1003 You need to buy more credits to send request.

Additional features

HTTP Request Limits

All request filters and limits can be set manually. By default, all of them are disabled.

Available request limitations include:

Available time periods:

Selecting one limitation and time period is required to send any validation for an email address request.

Blacklists

Block uninvited users by IP, domains and emails. Blacklist can be set globally or individually for each application.

Available block options:

Emails Status Filters

Verified emails can be passed or blocked. It’s possible store or omit emails for future sending campaigns.

Each application can filter emails by their statuses. Email Status Filters can’t be set globally.

Testing

Sandbox

All email statuses and responses can be tested, using sandbox endpoints. This allows for seamless integration, while not making a single real request.

HTTP Sandbox Request

GET https://api.sandbox.correct.email/v1/single/

Example requests

curl "https://api.sandbox.correct.email/v1/single/?key=your_api_key&email=email_to_be_checked"
  fetch('https://api.sandbox.correct.email/v1/single/?key=your_api_key&email=email_to_be_checked')
    .then(resp => {
        // ... response
    })
    .catch(error => {
        // ... error
    });
  var query url.Values
  query.Add("key", "your_api_key")
  query.Add("email", "email_to_be_checked")
  query.Add("ip", "ip_of_request")

  url, _ := url.Parse("https://api.sandbox.correct.email/v1/single/")
  url.RawQuery = query.Encode()

  resp, _ := http.Get(url.String())
from urllib.parse import urlencode
from urllib import request

query = (('key','your_api_key'),('email','email_to_be_checked'),('ip','ip_of_request'))
url = 'https://api.sandbox.correct.email/v1/single/' + '?' + urlencode(query)
req = request.Request(url, method='GET')
resp = request.urlopen(req)
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.ProtocolException;
import java.net.URL;
import java.net.URLEncoder;

public class JavaGetRequest {

    private static HttpURLConnection con;

    public static void main(String[] args) throws MalformedURLException,
            ProtocolException, IOException {

        String url = ("https://api.sandbox.correct.email/v1/single/");

        url += "?key=" + URLEncoder.encode("your_api_key", "UTF-8");
        url += "&email="+ URLEncoder.encode("email_to_be_checked", "UTF-8");
        url += "&ip="+ URLEncoder.encode("ip_of_request", "UTF-8");

        try {
            URL myurl = new URL(url);
            con = (HttpURLConnection) myurl.openConnection();

            con.setRequestMethod("GET");

            StringBuilder content;

            try (BufferedReader in = new BufferedReader(
                    new InputStreamReader(con.getInputStream()))) {

                String line;
                content = new StringBuilder();

                while ((line = in.readLine()) != null) {
                    content.append(line);
                    content.append(System.lineSeparator());
                }
            }

            System.out.println(content.toString());

        } finally {
            con.disconnect();
        }
    }
}

The above commands return JSON structured like this:

{
  "status": "success",
  "data": {
      "status": "temporary",
      "address": "clean@correct.email",
      "account": "clean",
      "domain": "correct.email",
      "anonymous": false,
      "tor": false,
      "spamIP": false,
      "blacklist": false,
      "duration": 0.121806599,
      "isSpammer": false
    }
}

URL Parameters

Parameter Required Description
key true One of test API keys provided below.
email true One of test email addresses provided below.

Test API keys and emails

Example response

{
    "status": "error",
    "data": {
        "id": "app_key_invalid",
        "code": 1000
    },
    "message": "Invalid application key"
}

Test API keys

API keys presented below are created for testing various error responses. Any API key other than the one provided below is valid (returns no error).

Key ID Code Meaning
app_key_invalid app_key_invalid 1000 API key is invalid.
app_account_blocked account_blocked 1001 Your account has been blocked.
app_rate_limit_exceeded live_rate_limit_reached 1002 You have reached your rate limit.
app_not_enough_credits not_enough_credits 1003 Account doesn't have enough credits for email check.
app_server_error server_error 1069 There was an error on our side.

Test emails

The emails provided below mock the real responses. Check the description of each of these emails for more information.

Email Description
clean@correct.email Email address with clean status
catch-all@correct.email Email address with catch-all status
special@correct.email Email address with special status
invalid@correct.email Email address with invalid status
spam-trap@correct.email Email address with spam-trap status
bad-mx@correct.email Email address with bad-mx status
bounced@correct.email Email address with bounced status
temporary@correct.email Email address with temporary status
unknown@correct.email Email address with unknown status
anonymous@correct.email Email address with anonymous set as true
tor@correct.email Email address with anonymous and tor set as true
spamip@correct.email Email address with spamIP set as true. Our system detected the provided IP address being spammy
spammer@correct.email Email address with spamEmail set as true. Our system detected the provided email address being spammy
blacklisted@correct.email Email address with blacklist set as true. This email is mocking the real blacklisted email