Email Validation (Deprecated)

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

This API endpoint is an email address verification service. We will verify 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 verification service can be found on our pricing page.

Mailgun’s email verification service is intended to verify 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 verification 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 verification 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 “Security” tab under the Account section of the Control Panel.

Warning

This version is deprecated. The new version of the Validations API is here api-email-validations

GET /address/validate

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

Parameter	Description
address	An email address to verify. (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 verification 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 verified 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 verify. (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 verification 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

Verify 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 com.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.model.verification.AddressValidationResponse

// ...

public AddressValidationResponse validateEmail() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
        .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.validateAddress("foo@mailgun.com");
}

# 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 = { address: "foo@mailgun.net" }
  public_key = "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"
  validate_url = "https://api.mailgun.net/v3/address/validate"
  RestClient::Request.execute method: :get, url: validate_url,
                                      headers: { params: url_params },
                                      user: 'api', password: public_key
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);
    }

}

import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func ValidateEmail(apiKey string) (mailgun.EmailVerification, error) {
    mv := mailgun.NewEmailValidator(apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mv.ValidateEmail(ctx, "foo@mailgun.net", false)
}

// This feature is deprecated
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "PUBLIC_API_KEY", domain: DOMAIN });

mailgun.validate('alice@example.com', function (error, body) {
  console.log(body);
});

Sample response without mailbox verification enabled:

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

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

Field Explanation:

Parameter	Type	Description
address	string	Email address being verified
did_you_mean	string	Null if nothing, however if a potential typo is made, the closest suggestion is provided
is_disposable_address	boolean	If the domain is in a list of disposable email addresses, this will be appropriately categorized
is_role_address	boolean	Checks the mailbox portion of the email if it matches a specific role type (‘admin’, ‘sales’, ‘webmaster’)
is_valid	boolean	Runs the email segments across a valid known provider rule list. If a violation occurs this value is false
mailbox_verification	string	If the mail_verification flag is enabled, a call is made to the ESP to return existence. (true, false, unknown or null)
parts	object	(display_name, domain, local_part): Parsed segments of the provided email address

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 com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode parseAddresses() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/address/parse")
            .basicAuth("api", API_KEY)
            .queryString("addresses", "bob@example.com, alice@example.com")
            .asJson();

        return request.getBody();
    }
}

# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY');
$addressList = 'Alice <alice@example.com>,bob@example.com';

# Issue the call to the client.
$result = $mgClient->emailValidation->parse($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 = { addresses:  "Alice <alice@example.com>,bob@example.com" }
  public_key = "pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7"
  parse_url = "https://api:#{public_key}@api.mailgun.net/v3/address/parse"
  RestClient::Request.execute method: :get, url: parse_url,
                                      headers: { params: url_params },
                                      user: 'api', password: public_key
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);
    }

}

import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func ParseAddress(apiKey string) ([]string, []string, error) {
    mv := mailgun.NewEmailValidator(apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mv.ParseAddresses(ctx,
        "Alice <alice@example.com>",
        "bob@example.com",
        // ...
    )
}

// This feature is deprecated
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "PUBLIC_API_KEY", domain: DOMAIN });

mailgun.parse([ 'alice@example.com', 'bob@example.com', 'fake@email.com' ], function (error, body) {
  console.log(body);
});

Sample response:

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

jQuery Plugin

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

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
});