Single Validation

Note:

The Validation 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.

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

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' \
    'https://api.mailgun.net/v4/address/validate?address=foo@mailgun.com'

Verify a single email address using the POST method.

Copy
Copied
curl -s --user 'api:YOUR_API_KEY' -X POST \
    'https://api.mailgun.net/v4/address/validate' \
    -d 'address=foo@mailgun.com'
}

Example of a failed mailbox verification result.

Copy
Copied
{
"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.

Copy
Copied
{
"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 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 validation 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.

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

Copy
Copied
GET /v4/address/validate?address=test123@test.com&provider_lookup=true
Copy
Copied
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:

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

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.
mailbox_quota_exceeded The mailbox is full and cannot accept more mail.
smtp_error An error was returned while attempting to validate the address.
smtp_timeout The MX host did not respond within our expected timeframe.

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.