Please enable JavaScript in your browser.

Introduction

The Free Email API checks if a single email address is from a free email provider and returns the results in either JSON or XML format.

NOTE: You will get your API key when you sign up for any MailboxValidator API plans.

Go to your dashboard to retrieve your API key.

GET https://api.mailboxvalidator.com/v2/email/free


Request Parameters

Parameter Description
email (required) The email address to check if is from a free email provider.
key (required) API key.
format (optional) Return the result in json (default) or xml format.
Valid values: json | xml

Successful Response Parameters

Parameter Description
email_address The input email address.
is_free Whether the email address is from a free email provider like Gmail or Hotmail.
Return values: true, false
credits_available The number of credits left to call the API.

Error Response Parameters

Parameter Description
error.error_code The error code if there is any error. See error table below.
error.error_message The error message if there is any error. See error table below.

Error Codes

error_code error_message
10000 Missing parameter.
10001 API key not found.
10002 API key disabled.
10003 API key expired.
10004 Insufficient credits.
10005 Unknown error.
10006 Invalid email syntax.

HTTP Error Codes

error_code HTTP Error
10000 400
10001 401
10002 401
10003 401
10004 401
10005 500
10006 400

Free Email API Sample Codes

<?php
$apiKey = 'Enter_License_Key';
$params['format']           = 'json';
$params['email']     = 'Enter_Email';

$query = '';

foreach($params as $key=>$value){
    $query .= '&' . $key . '=' . rawurlencode($value);
}

$try = 0;
do {
    ////////////
    //For https request, please make sure you have enabled php_openssl.dll extension.
    //
    //How to enable https
    //- Uncomment ;extension=php_openssl.dll by removing the semicolon in your php.ini, and restart the apache.
    //
    //In case you have difficulty to modify the php.ini, you can always make the http request instead of https.
    ////////////
    $result = file_get_contents('https://api.mailboxvalidator.com/v2/email/free?key=' . $apiKey . $query);
} while(!$result && $try++ < 3);

$data = json_decode($result);

print_r($data);
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;
import java.util.Hashtable;
import java.util.Map;

public class test {
    public static void main(String[] args) {
        try {
            String key = "Enter_License_Key";
            Hashtable<String, String> data = new Hashtable<String, String>();
            data.put("format", "json");
            data.put("email", "Enter_Email");
            
            String datastr = "";
            for (Map.Entry<String,String> entry : data.entrySet()) {
                datastr += "&" + entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), "UTF-8");
            }
            URL url = new URL("https://api.mailboxvalidator.com/v2/email/free?key=" + key + datastr);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            
            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
            }
            
            BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));
            
            String output;
            
            while ((output = br.readLine()) != null) {
                System.out.println(output);
            }
            conn.disconnect();
        }
        catch (MalformedURLException e) {
            e.printStackTrace();
        }
        catch (IOException e) {
            e.printStackTrace();
        }
    }
}
Imports System.Net
Imports System.IO
Imports System.Uri

Public Class _Default
    Inherits System.Web.UI.Page

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        Dim request As HttpWebRequest = Nothing
        Dim response As HttpWebResponse = Nothing

        Dim apiKey As String = "Enter_License_Key"
        Dim data As New Dictionary(Of String, String)

        data.Add("format", "json")
        data.Add("email", "Enter_Email")
        Dim datastr As String = String.Join("&", data.[Select](Function(x) x.Key & "=" & EscapeDataString(x.Value)).ToArray())

        request = Net.WebRequest.Create("https://api.mailboxvalidator.com/v2/email/free?key=" & apiKey & "&" & datastr)

        request.Method = "GET"
        response = request.GetResponse()

        Dim reader As System.IO.StreamReader = New IO.StreamReader(response.GetResponseStream())

        Page.Response.Write(reader.ReadToEnd)

    End Sub

End Class
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Net;
using System.IO;

namespace WebApplication1
{
    public partial class _Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            WebRequest request = null;
            WebResponse response = null;

            string apiKey = "Enter_License_Key";
            Dictionary<string, string> data = new Dictionary<string, string>();

            data.Add("format", "json");
            data.Add("email", "Enter_Email");
            string datastr = string.Join("&", data.Select(x => x.Key + "=" + System.Uri.EscapeDataString(x.Value)).ToArray());

            request = System.Net.WebRequest.Create("https://api.mailboxvalidator.com/v2/email/free?key=" + apiKey + "&" + datastr);

            request.Method = "GET";
            response = request.GetResponse();

            System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream());

            Page.Response.Write(reader.ReadToEnd());
        }
    }
}
import httplib
import urllib
import hashlib

p = { 'key': 'Enter_License_Key', 'format': 'json', 'email': 'Enter_Email' }

conn = httplib.HTTPConnection("api.mailboxvalidator.com")
conn.request("GET", "/v2/email/free?" + urllib.urlencode(p))
res = conn.getresponse()
print res.read()