Validates an email address using an external email validation API.
This function checks the validity, deliverability, and other attributes of an email address.
It returns a detailed dictionary containing information about the email's format, domain,
and SMTP server.
Args:
email (str): The email address to validate.
Returns:
dict[str, Any]: A dictionary containing detailed validation results. The dictionary
includes the following keys:
- "email" (str): The email address being validated.
- "autocorrect" (str): Suggested autocorrection if the email is invalid or malformed.
- "deliverability" (str): The deliverability status of the email (e.g., "DELIVERABLE").
- "quality_score" (str): A score representing the quality of the email address.
- "is_valid_format" (dict): Whether the email is in a valid format.
- "value" (bool): True if the format is valid, False otherwise.
- "text" (str): A textual representation of the format validity (e.g., "TRUE").
- "is_free_email" (dict): Whether the email is from a free email provider.
- "value" (bool): True if the email is from a free provider, False otherwise.
- "text" (str): A textual representation (e.g., "TRUE").
- "is_disposable_email" (dict): Whether the email is from a disposable email service.
- "value" (bool): True if the email is disposable, False otherwise.
- "text" (str): A textual representation (e.g., "FALSE").
- "is_role_email" (dict): Whether the email is a role-based email (e.g., "admin@domain.com").
- "value" (bool): True if the email is role-based, False otherwise.
- "text" (str): A textual representation (e.g., "FALSE").
- "is_catchall_email" (dict): Whether the domain uses a catch-all email address.
- "value" (bool): True if the domain is catch-all, False otherwise.
- "text" (str): A textual representation (e.g., "FALSE").
- "is_mx_found" (dict): Whether MX records are found for the email domain.
- "value" (bool): True if MX records are found, False otherwise.
- "text" (str): A textual representation (e.g., "TRUE").
- "is_smtp_valid" (dict): Whether the SMTP server for the email domain is valid.
- "value" (bool): True if the SMTP server is valid, False otherwise.
- "text" (str): A textual representation (e.g., "TRUE").
Example:
>>> await verify_email("thanos@snap.io")
{
"email": "thanos@snap.io",
"autocorrect": "",
"deliverability": "UNDELIVERABLE",
"quality_score": "0.00",
"is_valid_format": {
"value": true,
"text": "TRUE"
},
"is_free_email": {
"value": false,
"text": "FALSE"
},
"is_disposable_email": {
"value": false,
"text": "FALSE"
},
"is_role_email": {
"value": false,
"text": "FALSE"
},
"is_catchall_email": {
"value": false,
"text": "FALSE"
},
"is_mx_found": {
"value": false,
"text": "FALSE"
},
"is_smtp_valid": {
"value": false,
"text": "FALSE"
}
}
Raises:
ValueError: If the API key is not found in the environment variables.
requests.exceptions.HTTPError: If the API request fails (e.g., 4xx or 5xx error).
Exception: For any other unexpected errors.
