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 and not supported in the js library
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 and not supported in the js library
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
});