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).

The Email Validation API endpoint is available at:

v4/address/validate

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.

Note

A previous version of the API is described here Email Validation

Single Validation

Note

This feature is now available via the EU API.

Note

The validations feature is rate limited to a set number of active requests at a time. If you receive a 429 error, please wait and try again.

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)
POST /v4/address/validate

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

Form-Data Description
address An email address to validate. (Maximum: 512 characters)

Request Examples

Validate a single email address using the GET method.

curl --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();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function get_validate() {
  $params = array(
      "address" => "bob@example.com"
  );
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
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
  RestClient.get "https://api:PRIVATE_API_KEY"\
  "@api.mailgun.net/v4/address/validate",
  {params: {address: "foo@mailgun.net"}}
end
import (
   "encoding/json"
   "net/http"
)

type ValidationResponse struct {
   Address       string   `json:"address"`
   IsDisposable  bool     `json:"is_disposable_address"`
   IsRoleAddress bool     `json:"is_role_address"`
   Reason        []string `json:"reason"`
   Result        string   `json:"result"`
   Risk          string   `json:"risk"`
}


func validateAddress(email string) (vr ValidationResponse, err error) {

   // creating HTTP request and returning response

   client := &http.Client{}
   req, _ := http.NewRequest("GET", "https://api.mailgun.net/v4/address/validate", nil)
   req.SetBasicAuth("api", apiKey)
   param := req.URL.Query()
   param.Add("address", email)
   req.URL.RawQuery = param.Encode()
   response, err := client.Do(req)

   if err != nil {
       return
   }

   // decoding into validation response struct
   err = json.NewDecoder(response.Body).Decode(&vr)
   return
   }
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);
    }

}

Validate a single email address using the POST method.

curl --user 'api:PRIVATE_API_KEY' -X POST \
    https://api.mailgun.net/v4/address/validate \
    -F 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.post("https://api.mailgun.net/v4/address/validate")
            .basicAuth("api", PRIVATE_API_KEY)
            .field("address", "foo@mailgun.com")
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function post_validate() {
  $params = array(
      "address" => "bob@example.com"
  );
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def post_validate():
    return requests.post(
        "https://api.mailgun.net/v4/address/validate",
        auth=("api", "PRIVATE_API_KEY"),
        data={"address": "foo@mailgun.net"})
def post_validate
  RestClient.post "https://api:PRIVATE_API_KEY"\
  "@api.mailgun.net/v4/address/validate",
  {:address => "foo@mailgun.net", :multipart => true}
end
import (
       "bytes"
       "encoding/json"
       "mime/multipart"
       "net/http"
)

type ValidationResponse struct {
        Address       string   `json:"address"`
        IsDisposable  bool     `json:"is_disposable_address"`
        IsRoleAddress bool     `json:"is_role_address"`
        Reason        []string `json:"reason"`
        Result        string   `json:"result"`
        Risk          string   `json:"risk"`
}

func validateAddress(email string) (vr ValidationResponse, err error) {

        // creating HTTP request and returning response
        body := &bytes.Buffer{}
        writer := multipart.NewWriter(body)
        address, _ := writer.CreateFormField("address")
        _, _ = address.Write([]byte(email))
        writer.Close()

        client := &http.Client{}
        req, _ := http.NewRequest("POST", "https://api.mailgun.net/v4/address/validate", body)
        req.Header.Set("Content-Type", writer.FormDataContentType())
        req.SetBasicAuth("api", "api_key_here")
        response, err := client.Do(req)

        if err != nil {
                return
    }

        // decoding into validation response struct
        err = json.NewDecoder(response.Body).Decode(&vr)
        return
}
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetValidateChunk
{

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

    public static IRestResponse PostValidate ()
    {
        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");
        request.Method = Method.POST
        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"
}

Warning

For advanced users only

The provider_lookup query parameter provides users with the control to allow or prevent Mailgun from reaching out to the mailbox provider.

GET /v4/address/validate?address=test123@test.com&provider_lookup=true
POST /v4/address/validate?provider_lookup=true

‘true’ (default state) - A provider lookup will be performed if Mailgun’s internal analysis is insufficient.

‘false’ - A provider lookup will not be performed. If Mailgun does not have information on the recipient address, the API will return the following response:

{
    "address": "address@domain.com",
    "is_disposable_address": false,
    "is_role_address": false,
    "reason": ["no_data"],
    "result": "unknown",
    "risk": "unknown"
}

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 to the domain, 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, catch_all or unknown. Please see the Result Types section below for details on each result type.
risk string high, medium, low, or unknown Depending on the evaluation of all aspects of the given email.
root_address string (Optional) If the address is an alias; this will contain the root email address with alias parts removed.

Reason Explanation

Reason Description
unknown_provider The MX provider is an unknown provider.
no_mx / No MX host found The recipient domain does not have a valid MX host. Note: this reason will be consolidated to only “no_mx” in the future.
high_risk_domain Information obtained about the domain indicates it is high risk to send email to.
subdomain_mailer The recipient domain is identified to be a subdomain and is not on our exception list. Subdomains are considered to be high risk as many spammers and malicious actors utilize them.
immature_domain The domain is newly created based on the WHOIS information.
tld_risk The domain has a top-level-domain (TLD) that has been identified as high risk.
mailbox_does_not_exist The mailbox is undeliverable or does not exist.
mailbox_is_disposable_address The mailbox has been identified to be a disposable address. Disposable address are temporary, generally one time use, addresses.
mailbox_is_role_address The mailbox is a role based address (ex. support@…, marketing@…).
catch_all The validity of the recipient address cannot be determined as the provider accepts any and all email regardless of whether or not the recipient’s mailbox exists.
long_term_disposable The mailbox has been identified as a long term disposable address. Long term disposable addresses can be quickly and easily deactivated by users, but they will not expire without user intervention.
failed custom grammar check The mailbox failed our custom ESP local-part grammar check.

Result Types

Reason Description
deliverable The recipient address is considered to be valid and should accept email.
undeliverable The recipient address is considered to be invalid and will result in a bounce if sent to.
do not send The recipient address is considered to be highly risky and will negatively impact sending reputation if sent to.
catch_all The validity of the recipient address cannot be determined as the provider accepts any and all email regardless of whether or not the recipient’s mailbox exists.
unknown The validity of the recipient address cannot be determined for a variety of potential reasons. Please refer to the associated ‘reason’ array returned in the response.

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

It’s 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.

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.

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();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function get_bulk_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
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": 181854,
      "do_not_send": 5647,
      "undeliverable": 12116,
      "catch_all" : 2345,
      "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. (catch_all, deliverable, do_not_send, undeliverable, and unknown)
risk array nested risk assessment count (high, low, medium or unknown)

Get a list of bulk validation jobs:

This request will return a list of validation jobs in descending order by time created.

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)
            .queryString("limit", 2)
            .asJson();

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function get_bulk_validations() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/bulk?limit=2');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_mailing_list_validation_status():
    return requests.get(
        "https://api.mailgun.net/v4/address/validate/bulk",
        auth=('api', 'YOUR_API_KEY'),
        params={"limit": 2})
def get_mailing_list_validation_status
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v4/address/validate/bulk"\,
                 {params: {limit: 2}}
                 {|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";
        request.AddParameter ("limit", 2);
        return client.Execute (request);
    }

}
Parameter Type Description
limit integer Number of entries to return. Default: 500.

Sample Response:

    {
        "jobs":[
        {
            "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": 181854,
                    "do_not_send": 5647,
                    "undeliverable": 12116,
                    "catch_all" : 2345,
                    "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": 181854,
                    "do_not_send": 5647,
                    "undeliverable": 12116,
                    "catch_all" : 2345,
                    "unknown": 5613},
                "risk": {
                    "high": 17763,
                    "low": 142547,
                    "medium": 41652,
                    "unknown": 5613}
            }
        }],
    "total":3,
    "paging": {
      "next":
          "https://url_to_next_page",
      "previous":
          "https://url_to_previous_page",
      "first":
          "https://url_to_first_page",
      "last":
          "https://url_to_last_page"
    },
}

Results Fields Explanation:

Field Description
Deliverable The collection of validation jobs requested for.
Undeliverable The total number of validation jobs.
Do Not Send A collection of pagination links for traversing the validation jobs.
Catch All The total number of domain associated with result is considered a catch_all domain

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();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function upload_bulk_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'file'=> curl_file_create('subscribers.csv'))
  );

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
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);
    }

}
const DOMAIN = 'YOUR_DOMAIN_NAME';

const formData = require('form-data');
const Mailgun = require('mailgun.js');

const mailgun = new Mailgun(formData);
const path = require('path');
const fsPromises = require('fs').promises;
const filepath = path.resolve(__dirname, '../emailsValidationList.csv');

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const file = {
      filename: 'emailsValidationList.csv',
      data: await fsPromises.readFile(filepath)
    };

    const validationRes = await client.validate.multipleValidation.create('validationList', {file: file});
    console.log('validationRes', validationRes);
  } catch (error) {
      console.error(error);
  }
})();

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();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function delete_bulk_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME');
  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
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."
}

Bulk Validation Preview

Note

Bulk validation preview performs a free analysis of a list of email addresses allowing you to make an informed decision to run a complete bulk validation or not. Given a preview name and an uploaded file of email addresses, a preliminary validation run will be preformed. The results of the preview will be, on average, an estimate of the deliverability and risk of the emails provide. This evaluation is based on a statistical sampling of the list provided.

Note

It’s 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/preview

Get list of all bulk validation previews.

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

Create a bulk validation preview.

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

Check the current status of a bulk validation preview.

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

Delete a bulk validation preview.

PUT /v4/address/validate/preview/<list_id>

Promote a bulk validation preview to a bulk validation job.

Get the results of a bulk validation preview:

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

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

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function get_bulk_preview() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/preview/LIST_NAME');
  $result = curl_exec($ch);
  curl_close($ch);

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

public class GetBulkValidationPreview
{

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

    public static IRestResponse GetBulkPreview ()
    {
        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/preview/{list}";
        return client.Execute (request);
    }

}

Sample Response:

{
  "preview": {
    "id": "test_500",
    "valid": true,
    "status": "preview_complete",
    "quantity": 8,
    "created_at": 1590080191,
    "summary": {
      "result": {
        "deliverable": 37.5,
        "undeliverable": 23,
        "catch_all" : 2,
        "unknown": 37.5
      },
      "risk": {
        "high": 25,
        "low": 25,
        "medium": 12.5,
        "unknown": 37.5
      }
    }
  }
}

Field Explanation:

Field Type Description
id string list_id name given when the list was initially created
created_at string Date/Time that the request was initiated
quantity integer number of total items in the list to be previewed
status string current state of the list validation request. (preview_processing, preview_complete)
valid bool a boolean to represent if the list is valid
summary collection summary of the validations in the list provided
result array nested results averaged. (deliverable, undeliverable, catch_all and unknown)
risk array nested risk assessment count (high, low, medium or unknown)

Get a list of bulk validation previews:

This request will return a list of bulk validation previews.

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

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

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function get_bulk_validations() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/preview');
  $result = curl_exec($ch);
  curl_close($ch);

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

public class GetBulkPreviews
{

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

    public static IRestResponse GetPreviews ()
    {
        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/preview";
        return client.Execute (request);
    }

}

Sample Response:

{
  "previews": [
    {
      "id": "test_500",
      "valid": true,
      "status": "preview_complete",
      "quantity": 8,
      "created_at": 1590080191,
      "summary": {
        "result": {
          "deliverable": 37.5,
          "do_not_send": 0,
          "undeliverable": 23,
          "catch_all": 2,
          "unknown": 37.5
        },
        "risk": {
          "high": 25,
          "low": 25,
          "medium": 12.5,
          "unknown": 37.5
        }
      }
    },
    {
      "id": "test_501",
      "valid": true,
      "status": "preview_complete",
      "quantity": 8,
      "created_at": 1590155015,
      "summary": {
        "result": {
          "deliverable": 37.5,
          "do_not_send": 0,
          "undeliverable": 23,
          "catch_all": 2,
          "unknown": 37.5
        },
        "risk": {
          "high": 25,
          "low": 25,
          "medium": 12.5,
          "unknown": 37.5
        }
      }
    }
  ]
}

Response Fields Explanation:

Field Type Description
previews collection A collection of bulk validation previews.

Create a bulk validation preview:

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

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

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function create_bulk_preview() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/preview/LIST_NAME');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
      'file'=> curl_file_create('subscribers.csv'))
  );

  $result = curl_exec($ch);
  curl_close($ch);

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

public class BulkPreview
{

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

    public static IRestResponse CreateBulkPreview ()
    {
        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/preview/{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": "test_501",
  "message": "The bulk preview was submitted."
}

Delete a bulk validation preview:

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

        return request.getBody();
    }
}
# Currently, the PHP SDK does not support the v4 Validations endpoint.
# Consider using the following php curl function.
function delete_bulk_preview() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v4/address/validate/preview/LIST_NAME');
  $result = curl_exec($ch);
  curl_close($ch);

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

public class DeleteBulkPreview
{

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

    public static IRestResponse DeletePreview()
    {
        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/preview/{list}";
        request.AddParameter ("list", "LIST_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

}
Sample Response:
A 204 will be returned upon successful deletion.