Overview
So you've decided to take the step to implement our Email Validation API. A good place to get started is to test the Email Validation API in the Mailgun Control Panel. This way, you can quickly and easily submit validations and view the JSON response from the API.
If your account has it, the Validations option will be on the left-hand navigation pane of your Control Panel. Additionally, your account user (used to login to the Control Panel) will not have permission to perform validations if your account user's role is Support, Billing, or Analyst.
Validation fields explained
So, once you've validated an address, what does the response mean? Let's take a look at the data listed in the JSON response as well as displayed in the Mailgun Control Panel.
| Field | Description |
| address | The address being validated |
| did_you_mean | A suggested alternative email address, if available, based on common misspellings or typos; if no suggestion is available, this field will be blank (technically: null) |
| engagement | Contains the fields is_bot (whether the recipient is a bot) and engaged (whether the recipient has engaged at all) fields, each of which will be either true or false. Accounts on a Contract plan also have access to the additional field engagement that lists the specific type of engagement Mailgun has seen with the given email address. Please see our API documentation for more details |
| is_disposable_address | Returns true if the domain is a known disposable email address |
| is_role_address | Returns true if the address is role-based, e.g. support@example.com or info@example.com or sales@example.com |
| reason | Potential reason why a specific validation may be unsuccessful. Please see the Reason field explained section below |
| result | Provides guidance whether to send to this email address any longer. Please see the Result field explained section below |
| risk | Following an evaluation of all aspects of a given email, returns a result of either high, medium, low, or unknown
|
| root_address | (Optional) If the address is an alias, this will contain the root email address with alias parts removed |
Reason field explained
The reason field will contain one reason from a large list of potential reasons why a specific validation may be unsuccessful.
| 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 associated with the email address 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 field explained
The result field will contain one conclusive result in order to provide guidances whether to send to this email address any longer.
| Result | 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 list returned in the response |
SDKs available to hasten development
We also have community-driven SDKs for popular programming languages to help you implement Mailgun Email Validation into your project.
You are now ready to begin making API calls to start validating email addresses. To see the full technical details on how to implement and make calls to the Email Validation API, please see our technical documentation here.
FAQ
Why switch from using Validations API v3 to v4?
Some customers may still be using the older Validations v3 API instead of the newer Validation v4 API. If that is you, we recommend upgrading since v4 has the latest security enhancements.
While you may continue to use the V3 endpoint, we strongly recommend that you switch to our V4 endpoint to benefit from the enhanced security features. Please refer to our Validations API documentation.
How can I limit the number of public validations my account can perform?
- First, log in to the Mailgun Control Panel (if you have not already done so).
- Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
- Next, click the Manage Account option. Alternatively, you can use this direct link.
- Now, click on the Edit button associated with Public Verification Limit setting in the Mailgun settings section.
- Adjust your limit. (Note: this is a hard limit. Once your validations job exceeds this limit, your account will be disabled).
What is the difference between private and public validation endpoint?
The public endpoint is meant to be used within front-end applications (and is only available on version 3 of the Validations API). To protect the public API Key it has an initial monthly limit that can be adjusted. The private endpoint is meant for back-end applications and does not have this limitation.
What account user roles can perform email validations?
Only users with admin and developer roles can perform email validations using the account. Users with the support, billing, or analyst roles cannot perform email validations.
Can email validations detect if a mailbox exists?
Yes, it's one of the possible Reasons provided (see above) when validating an email address.
Need Support?
Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!