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 “Security” tab under the Account section of the Control Panel.

Note

A previous version of the API is described here Email Validation

GET /v4/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.

Example

Validate a single email address.

curl -G --user 'api:PRIVATE_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate \
    --data-urlencode address='foo@mailgun.net'
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 validateEmail() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v4/address/validate")
            .basicAuth("api", PRIVATE_API_KEY)
            .queryString("address", "foo@mailgun.com")
            .asJson();

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

# Instantiate the client.
$mgClient = new Mailgun('PRIVATE_API_KEY');
$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/v4/address/validate",
        auth=("api", "PRIVATE_API_KEY"),
        params={"address": "foo@mailgun.net"})
def get_validate
  url_params = { address: "foo@mailgun.net" }
  public_key = "PRIVATE_API_KEY"
  validate_url = "https://api.mailgun.net/v4/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/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "PRIVATE_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/address/validate";
        request.AddParameter ("address", "foo@mailgun.net");
        return client.Execute (request);
    }

}

Example of a failed mailbox verification result.

{
    "address": "nonexistentemail@realdomain.com",
    "is_disposable_address": false,
    "is_role_address": false,
    "reason": [mailbox_does_not_exist],
    "result": "undeliverable",
    "risk": "high"
}

Example of successful mailbox verification result.

{
    "address": "existingemail@realdomain.com",
    "is_disposable_address": false,
    "is_role_address": false,
    "reason": [],
    "result": "deliverable",
    "risk": "low"
}

Field Explanation:

Parameter Type Description
address string Email address being validated
did_you_mean string (Optional) 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’)
reason array List of potential reasons why a specific validation may be unsuccessful.
result string Either deliverable, undeliverable or unknown status given the evaluation.
risk string high, medium, low or null Depending on the evaluation of all aspects of the given email.

Bulk Validation

Note

Bulk Validation allows for the validation of a list of email addresses. Given a list name and an uploaded file of email addresses, a backend processing job will be run to validate the list. Once the validations have all been completed, the results will be provided with download links.

Note

Its important to upload as multi-part/form-data where the file is defined by file.

Currently only raw csv and gzip are supported.

The column header for emails needs to be either email or email_address

Warning

Lists must comply to either UTF-8 or ASCII encoding and not have a ‘@’ in the name.

GET /v4/address/validate/bulk

Get list of all bulk validation jobs for an account.

POST /v4/address/validate/bulk/<list_id>

Create a bulk validation job.

GET /v4/address/validate/bulk/<list_id>

Check the current status of a bulk validation job.

DELETE /v4/address/validate/bulk/<list_id>

Cancel current running bulk validation job.

Bulk Validation Examples

Get the status of a bulk validation job:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME
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 getMailingListValidation() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/address/validate/bulk/{list}")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
def get_mailing_list_validation_status():
    return requests.get(
        "https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME",
        auth=('api', 'YOUR_API_KEY'))
def get_mailing_list_validation_status
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/address/validate/bulk/LIST_NAME"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetBulkValidationChunk
{

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

    public static IRestResponse GetBulkValidation ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("list", "LIST_NAME", ParameterType.UrlSegment);
        request.Resource = "/address/validate/bulk/{list}";
        return client.Execute (request);
    }

}

Sample Response:

{
  "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
  "download_url": {
    "csv": "<download_link>",
    "json": "<download_link>"
  },
  "id": "bulk_validations_sandbox_mailgun_org",
  "quantity": 207665,
  "records_processed": 207665,
  "status": "uploaded",
  "summary": {
    "result": {
      "deliverable": 184199,
      "do_not_send": 5647,
      "undeliverable": 12116,
      "unknown": 5613
    },
    "risk": {
      "high": 17763,
      "low": 142547,
      "medium": 41652,
      "unknown": 5613
    }
  }
}

Field Explanation:

Parameter Type Description
created_at string Date/Time that the request was initiated
download_url array csv and json representation of the download link for the results of the bulk validations
id string list_id name given when the list was initially created
quantity integer number of total items in the list to be validated
records_processed integer de-duplicated total of validated email addresses
status string current state of the list validation request. (created, processing, completed, uploading, uploaded, and failed)
summary collection summary of the validations in the list provided
result array nested results count. (deliverable, do_not_send, undeliverable, and unknown)
risk array nested risk assessment count (high, low, medium or unknown)

Get the status of all bulk validation jobs:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/bulk
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 getMailingListValidation() throws UnirestException {

        HttpResponse<JsonNode> request = Unirest.get("https://api.mailgun.net/v4/address/validate/bulk")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
def get_mailing_list_validation_status():
    return requests.get(
        "https://api.mailgun.net/v4/address/validate/bulk",
        auth=('api', 'YOUR_API_KEY'))
def get_mailing_list_validation_status
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/address/validate/bulk"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetBulkValidationsChunk
{

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

    public static IRestResponse GetBulkValidation ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/address/validate/bulk";
        return client.Execute (request);
    }

}

Sample Response:

[
    {
        "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
        "download_url": {
            "csv": "<download_link>",
            "json": "<download_link>"
        }
        "id": "bulk_validations_sandbox2_mailgun_org",
        "quantity": 207665,
        "records_processed": 207665,
        "status": "uploaded",
        "summary": {
            "result": {
                "deliverable": 184199,
                "do_not_send": 5647,
                "undeliverable": 12116,
                "unknown": 5613},
            "risk": {
                "high": 17763,
                "low": 142547,
                "medium": 41652,
                "unknown": 5613}
        }
    },
    {
        "created_at": "Tue, 23 Feb 2019 21:30:03 GMT",
        "download_url": {
            "csv": "<download_link>",
            "json": "<download_link>"
        }
        "id": "bulk_validations_sandbox_mailgun_org",
        "quantity": 207,
        "records_processed": 207,
        "status": "uploaded",
        "summary": {
            "result": {
                "deliverable": 184199,
                "do_not_send": 5647,
                "undeliverable": 12116,
                "unknown": 5613},
            "risk": {
                "high": 17763,
                "low": 142547,
                "medium": 41652,
                "unknown": 5613}
        }
    }
]

Create a bulk validation job:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME \
    -F 'file=@/path/to/file' \
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 validateMailingList() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME")
            .basicAuth("api", API_KEY)
            .field("file", new File("/path/to/file"))
            .asJson();

        return request.getBody();
    }
}
def validate_mailing_list():
    return requests.post(
        "https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME",
        files = {'file': open('/path/to/file','rb')},
        auth=('api', 'YOUR_API_KEY'))
def validate_mailing_list
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v4/address/validate/bulk/LIST_NAME",
                  fields_hash.merge(:file => File.new('/path/to/file')))
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class BulkValidationChunk
{

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

    public static IRestResponse BulkValidation ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "address/validate/bulk/{list}";
        request.AddParameter ("list", "LIST_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.POST;
        request.AddFile("file", @"/path/to/file");
        return client.Execute (request);
    }

}

Sample Response:

{
 "id":"myemails"
 "message": "The validation job was submitted."
}

Cancel a bulk validation job:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME
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 cancelMailingListValidation() throws UnirestException {
        url = "https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME"
        HttpResponse <JsonNode> request = Unirest.delete(url)
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
def cancel_bulk_validation():
    return requests.delete(
        ("https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME"),
        auth=('api', 'YOUR_API_KEY'))
def cancel_bulk_validation
  RestClient.delete("https://api:YOUR_API_KEY" \
                    "@api.mailgun.net/v4/address/validate/bulk/LIST_NAME")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class DeleteBulkValidationChunk
{

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

    public static IRestResponse CancelBulkValidation()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v4");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "address/validate/bulk/{list}";
        request.AddParameter ("list", "LIST_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

}

Sample Response:

{
 "message": "Validation job canceled."
}