Response

This guide explains the structure and meaning of the response you receive when validating an email address using the Mails API.

Response Structure

The API returns a JSON object with two main fields: data and error. When the validation is successful, data contains the validation results and error is null.

{
  "data": {
    // Validation results here
  },
  "error": null
}

Data Fields

Here's a breakdown of each field in the data object:

Field	Type	Description
id	string	Unique identifier for this validation request
email	string	The email address that was validated
username	string	The part of the email address before the @ symbol (null if not available)
domain	string	The domain part of the email address (null if not available)
mx_record	string	The MX (Mail Exchanger) record for the email domain
score	number	Validation score from 0 to 100, indicating the likelihood of the email being valid
isv_format	boolean	Whether the email format is valid
isv_domain	boolean	Whether the domain is valid
isv_mx	boolean	Whether the MX record is valid
isv_noblock	boolean	Whether the email is not in block lists
isv_nocatchall	boolean	Whether the domain doesn't have a catch-all policy
isv_nogeneric	boolean	Whether the email is not a generic address
is_free	boolean	Whether the email is from a free email provider
result	string	Overall validation result (see Result Types below)
reason	string	Reason for the validation result (see Reason Types below)

Result Types

The result field can have one of the following values:

Value	Description
"deliverable"	The email is valid and can receive messages
"undeliverable"	The email is invalid or cannot receive messages
"risky"	The email might be valid but has some risk factors
"unknown"	The validation process couldn't determine the email's status

Reason Types

The reason field provides more detail about the validation result:

Value	Description
"accepted_email"	The email was accepted by the mail server
"invalid_format"	The email format is invalid
"invalid_domain"	The email's domain is invalid
"invalid_smtp"	The email failed SMTP verification
"rejected_email"	The email was rejected by the mail server
"catch_all"	The domain accepts all emails (catch-all policy)
"disposable"	The email is from a disposable email service
"no_connect"	Couldn't connect to the mail server
"timeout"	The validation process timed out
"other"	Other unspecified reason

Example Response

Here's an example of a complete response:

{
  "data": {
    "id": "4c6b837a-1463-4f40-8d0b-b3afa31a4935",
    "email": "[email protected]",
    "username": "elon",
    "domain": "x.com",
    "mx_record": "aspmx.l.google.com",
    "score": 80,
    "isv_format": true,
    "isv_domain": true,
    "isv_mx": true,
    "isv_noblock": true,
    "isv_nocatchall": false,
    "isv_nogeneric": true,
    "is_free": false,
    "result": "risky",
    "reason": "catch_all"
  },
  "error": null
}

In this example:

• The email format is valid (isv_format: true)
• The domain and MX record are valid (isv_domain: true, isv_mx: true)
• The email is not blocked (isv_noblock: true)
• The domain has a catch-all policy (isv_nocatchall: false)
• It's not a generic email address (isv_nogeneric: true)
• It's not from a free email provider (is_free: false)
• The overall result is "risky" due to the catch-all policy

Interpreting the Results

• A high score and "deliverable" result generally indicate a valid, usable email address.
• "Risky" results may require additional verification or caution.
• "Undeliverable" results suggest the email should not be used.
• Consider both the result and reason fields for a complete understanding of the email's status.

Remember to handle all possible result and reason types in your application to ensure robust email validation processing.