Email Validation

This API endpoint is an email address validation service. We will validate the given address based on:

  • Mailbox detection
  • Syntax checks (RFC defined grammar)
  • DNS validation
  • Spell checks
  • Email Service Provider (ESP) specific local-part grammar (if available).

Pricing details for Mailgun’s email validation service can be found on our pricing page.

Mailgun’s email validation service is intended to validate email addresses submitted through forms like newsletters, online registrations and shopping carts. Refer to our Acceptable Use Policy (AUP) for more information about how to use the service appropriately.

Different email validation rates are given based on the API endpoint. Both the public and private API endpoints are limited to a burst per minute rate. The public endpoints have a default limit of calls per month, which can be changed, to prevent abuse of the public API key. The use of private API endpoints for email validation is encouraged and there is no limit past the initial burst per minute rate. It is highly suggested that the private key is used whenever possible.

Warning

Do not use your Mailgun private API key on publicly accessible code. Instead, use your Mailgun public key, available in the My Account tab of the Control Panel.

GET /address/validate

Given an arbitrary address, validates address based off defined checks.

Parameter Description
address An email address to validate. (Maximum: 512 characters)
api_key If you cannot use HTTP Basic Authentication (preferred), you can pass your public api_key in as a parameter.
mailbox_verification

If set to true, a mailbox verification check will be performed against the address.

The default is False.

GET /address/parse

Parses a delimiter-separated list of email addresses into two lists: parsed addresses and unparsable portions. The parsed addresses are a list of addresses that are syntactically valid (and optionally pass DNS and ESP specific grammar checks). The unparsable list is a list of character sequences that could not be parsed (or optionally failed DNS or ESP specific grammar checks). Delimiter characters are comma (,) and semicolon (;).

Parameter Description
addresses A delimiter separated list of addresses. (Maximum: 8000 characters)
syntax_only Perform only syntax checks or DNS and ESP specific validation as well. (true by default)
api_key If you cannot use HTTP Basic Authentication (preferred), you can pass your public api_key in as a parameter.
GET /address/private/validate

Addresses are validated based off defined checks.

This operation is only accessible with the private API key and not subject to the daily usage limits.

Parameter Description
address An email address to validate. (Maximum: 512 characters)
mailbox_verification

If set to true, a mailbox verification check will be performed against the address.

The default is False.

GET /address/private/parse

Parses a delimiter-separated list of email addresses into two lists: parsed addresses and unparsable portions. The parsed addresses are a list of addresses that are syntactically valid (and optionally pass DNS and ESP specific grammar checks). The unparsable list is a list of character sequences that could not be parsed (or optionally failed DNS or ESP specific grammar checks). Delimiter characters are comma (,) and semicolon (;).

This operation is only accessible with the private API key and not subject to the daily usage limits.

Parameter Description
addresses A delimiter separated list of addresses. (Maximum: 8000 characters)
syntax_only Perform only syntax checks or DNS and ESP specific validation as well. (true by default)
api_key If you can not use HTTP Basic Authentication (preferred), you can pass your private api_key in as a parameter.

Example

Validate a single email address.

curl -G --user 'api:pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7' -G \
    https://api.mailgun.net/v3/address/validate \
    --data-urlencode address='foo@mailgun.net'
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse ValidateAddress() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        return mgRoot
            .path("/address/validate")
            .queryParam("address", "foo@mailgun.net")
            .request()
            .buildGet()
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7');
$validateAddress = 'foo@mailgun.net';

# Issue the call to the client.
$result = $mgClient->get("address/validate", array('address' => $validateAddress));
# is_valid is 0 or 1
$isValid = $result->http_response_body->is_valid;
def get_validate():
    return requests.get(
        "https://api.mailgun.net/v3/address/validate",
        auth=("api", "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"),
        params={"address": "foo@mailgun.net"})
def get_validate
  url_params = {}
  url_params[:address] = "foo@mailgun.net"
  query_string = url_params.collect {|k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}"}.
    join("&")
  RestClient.get "https://api:pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"\
  "@api.mailgun.net/v3/address/validate?#{query_string}"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetValidateChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetValidate ().Content.ToString ());
    }

    public static IRestResponse GetValidate ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7");
        RestRequest request = new RestRequest ();
        request.Resource = "/address/validate";
        request.AddParameter ("address", "foo@mailgun.net");
        return client.Execute (request);
    }

}
func ValidateEmail(domain, publicApiKey string) (mailgun.EmailVerification, error) {
  mg := mailgun.NewMailgun(domain, "", publicApiKey)
  return mg.ValidateEmail("foo@mailgun.net")
}

Simple sample response:

{
    "address": "foo@mailgun.net",
    "did_you_mean": null,
    "is_disposable_address": false,
    "is_role_address": true,
    "is_valid": true,
    "parts": {
        "display_name": null,
        "domain": "mailgun.net",
        "local_part": "foo"
    }
}

Sample response with mailbox verification enabled:

{
    "address": "foo@mailgun.net",
    "did_you_mean": null,
    "is_disposable_address": false,
    "is_role_address": true,
    "is_valid": true,
    "mailbox_verification": "true",
    "parts": {
        "display_name": null,
        "domain": "mailgun.net",
        "local_part": "foo"
    }
}

Note

is_valid returns true when an address is parsable, passes known grammar checks and an SMTP server is present. The role-based and disposable address check will not impact the state of the is_valid result. The user should determine whether or not to permit the address to be used.

Note

The mailbox verification attribute will return true if the email is valid, false if the email was invalid, or unknown if the SMTP request could not be completed. Unknown will also be returned if mailbox verification is not supported on the target mailbox provider. The outcome of the verification check will not impact the state of the is_valid result.

Parse a list of email addresses.

curl -G --user 'api:pubkey-501jygdalut926-6mb1ozo8ay9crlc28' \
    https://api.mailgun.net/v3/address/parse \
    --data-urlencode addresses='Alice <alice@example.com>,bob@example.com'
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse ParseAddresses() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        return mgRoot
            .path("/address/parse")
            .queryParam("addresses", "Alice <alice@example.com>,bob@example.com")
            .request()
            .buildGet()
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7');
$addressList = 'Alice <alice@example.com>,bob@example.com';

# Issue the call to the client.
$result = $mgClient->get("address/parse", array('addresses' => $addressList));
def get_parse():
    return requests.get(
        "https://api.mailgun.net/v3/address/parse",
        auth=("api", "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"),
        params={"addresses": "Alice <alice@example.com>,bob@example.com"})
def get_parse
  url_params = {}
  url_params[:addresses] = "Alice <alice@example.com>,bob@example.com"
  query_string = url_params.collect {|k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}"}.
    join("&")
  RestClient.get "https://api:pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"\
  "@api.mailgun.net/v3/address/parse?#{query_string}"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetParseChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetParse ().Content.ToString ());
    }

    public static IRestResponse GetParse ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7");
        RestRequest request = new RestRequest ();
        request.Resource = "/address/parse";
        request.AddParameter ("addresses",
                              "Alice <alice@example.com>,bob@example.com");
        return client.Execute (request);
    }

}
func ParseAddress(domain, publicApiKey string) ([]string, []string, error) {
  mg := mailgun.NewMailgun(domain, "", publicApiKey)
  return mg.ParseAddress(
    "Alice <alice@example.com>",
    "bob@example.com",
    // ...
  )
}

Sample response:

    {
    "parsed": [
        "Alice <alice@example.com>",
        "bob@example.com"
    ],
    "unparseable": [
    ]
}

jQuery Plugin

We also have a jQuery plugin you can use for front-end email validation.

Just remember to use your public Mailgun API key.

Attaching to a form:

$('jquery_selector').mailgun_validator({
    api_key: 'api-key',
    in_progress: in_progress_callback, // called when request is made to validator
    success: success_callback,         // called when validator has returned
    error: validation_error,           // called when an error reaching the validator has occured
});