Email Verifications

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.

Note

Our Single and Bulk Email Verification service is available via the EU API.

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

The Email Validation/Verification API endpoint is available at:

v4/address/validate

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.

Note

A previous version of the API is described here Email Validation (Deprecated)

Single Verification

Note

The verifications 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, verifies address based off defined checks.

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

POST /v4/address/validate

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

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

Request Examples

Verify 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.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");
}

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

}

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const validationRes = await client.validate.get('foo@mailgun.net');
    console.log('validationRes', validationRes);
  } catch (error) {
    console.error(error);
  }
})();

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

// ...

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

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

# 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 verified
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 verification may be unsuccessful.
result	string	Either deliverable, undeliverable, do_not_send, 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 Verification

Note

Bulk Verification allows for the verification 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 verify the list. Once the verifications 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. While there is no limit on the number of email addresses that can be provided, the file size cannot exceed 25MB.

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 verification jobs.

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

Create a bulk verification job. The list_id is an arbitrary unique identifier provided by the API caller.

Please note that the max number of verification jobs that can be processed in parallel is 10. If this number is exceeded, a 400 response will be returned.

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

Check the current status of a bulk verification job.

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

This endpoint can be used to cancel an in-progress bulk verification job or delete results for a completed bulk verification job. When this endpoint is called for an “uploaded” job, associated result files will be deleted and the job’s status will be set to “deleted”.

Get the status of a bulk verification job:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME

   import com.mailgun.api.v4.MailgunEmailVerificationApi;
   import com.mailgun.client.MailgunClient;
   import com.mailgun.model.verification.BulkVerificationJobStatusResponse

   // ...

   public BulkVerificationJobStatusResponse getBulkVerificationJobStatus() {
       MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
               .createApi(MailgunEmailVerificationApi.class);

       return mailgunEmailVerificationApi.getBulkVerificationJobStatus(LIST_NAME);
   }
}

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

}

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const jobStatus = await client.validate.multipleValidation.get('validationList');
    console.log('jobStatus ', jobStatus);
  } catch (error) {
    console.error(error);
  }
})();

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 verifications
id	string	list_id name given when the list was initially created
quantity	integer	number of total items in the list to be verified
records_processed	integer	de-duplicated total of verified email addresses
status	string	current state of the list verification request. (created, processing, completed, uploading, uploaded, and failed)
summary	collection	summary of the verifications 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 verification jobs:

This request will return a list of verification 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.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import com.mailgun.model.verification.BulkVerificationJobListResponse;

// ...

public BulkVerificationJobListResponse getBulkVerificationJobList() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.getBulkVerificationJobList();
}

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

}

const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const validationsJobsList = await client.validate.multipleValidation.list();
    console.log('validationsJobsList', validationsJobsList);
  } catch (error) {
    console.error(error);
  }
})();

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 verification jobs requested for.
Undeliverable	The total number of verification jobs.
Do Not Send	A collection of pagination links for traversing the verification jobs.
Catch All	The total number of domain associated with result is considered a catch_all domain

Create a bulk verification 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.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import com.mailgun.model.verification.BulkVerificationCreatingResponse;
import com.mailgun.model.verification.BulkVerificationStatusRequest;
import java.io.File;

// ...

public BulkVerificationCreatingResponse createBulkVerificationJob() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    BulkVerificationStatusRequest request = BulkVerificationStatusRequest.builder()
            .file(new File("/path/to/file"))
            .build();

    return mailgunEmailVerificationApi.createBulkVerificationJob(LIST_NAME, request);
}

# 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';

import formData from 'form-data';
import Mailgun from 'mailgun.js';
import path from 'node:path';
import fs from 'node:fs/promises';

const mailgun = new Mailgun(formData);
const filepath = path.resolve('../emailsValidationList.csv');

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const file = {
      filename: 'emailsValidationList.csv',
      data: await fs.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 verification job:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v4/address/validate/bulk/LIST_NAME

import com.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;

// ...

public String cancelBulkVerificationJob() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.cancelBulkVerificationJob(LIST_NAME);
}

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

}

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const canceledJob = await client.validate.multipleValidation.destroy('validationList');
    console.log('canceledJob ->', canceledJob);
  } catch (error) {
    console.error(error);
  }
})();

Sample Response:

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

Bulk Verification Preview

Note

Bulk verification preview performs a free analysis of a list of email addresses allowing you to make an informed decision to run a complete bulk verification or not. Given a preview name and an uploaded file of email addresses, a preliminary verification 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. While there is no limit on the number of email addresses that can be provided, the file size cannot exceed 25MB.

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 verification previews.

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

Create a bulk verification preview. The list_id is an arbitrary unique identifier provided by the API caller.

Please note that the max number of verification previews that can be processed in parallel is 10. If this number is exceeded, a 400 response will be returned.

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

Check the current status of a bulk verification preview.

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

Delete a bulk verification preview.

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

Promote a bulk verification preview to a bulk verification job.

Get the results of a bulk verification preview:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/preview/LIST_NAME

import com.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import com.mailgun.model.verification.BulkVerificationPreviewResponse;

// ...

public BulkVerificationPreviewResponse getBulkPreview() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.getBulkVerificationPreviewStatus(LIST_NAME);
}

# 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 verification request. (preview_processing, preview_complete)
valid	bool	a boolean to represent if the list is valid
summary	collection	summary of the verifications 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 verification previews:

This request will return a list of bulk verification previews.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v4/address/validate/preview

import com.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import com.mailgun.model.verification.BulkVerificationPreviewListResponse;

// ...

public BulkVerificationPreviewListResponse getBulkPreviews() {
     MailgunEmailVerificationApi mailgunEmailVerificationApi  = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.getBulkVerificationPreviewList();
}

# 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 verification previews.

Create a bulk verification 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.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import com.mailgun.model.verification.BulkVerificationCreatingResponse;
import com.mailgun.model.verification.BulkVerificationStatusRequest;
import java.io.File;

// ...

public BulkVerificationCreatingResponse createBulkPreview() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    BulkVerificationStatusRequest request = BulkVerificationStatusRequest.builder()
            .file(new File("/path/to/file"))
            .build();

    return mailgunEmailVerificationApi.createBulkVerificationPreview(LIST_NAME, request);
}

# 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 verification preview:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v4/address/validate/preview/LIST_NAME

import com.mailgun.api.v4.MailgunEmailVerificationApi;
import com.mailgun.client.MailgunClient;
import feign.Response;

// ...

public Response cancelBulkPreview() {
    MailgunEmailVerificationApi mailgunEmailVerificationApi = MailgunClient.config(API_KEY)
            .createApi(MailgunEmailVerificationApi.class);

    return mailgunEmailVerificationApi.deleteBulkVerificationPreview(LIST_NAME);
}

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

Alerts

Use our alerting platform to be notified when your bulk email verification jobs complete. To learn more, see the alerting documentation.