`check_blacklist`: check the email against the blacklist of domains downloaded from <https://github.com/disposable-email-domains/disposable-email-domains>; defaults to `True`
`smtp_from_address`: the email address used for the sender in the SMTP conversation; if set to `None` (the default), the email_address parameter is used as the sender as well
`address_types`: The IP address types to use. pass a `frozenset` if you want to change the default `frozenset([IPv6Address, IPv4Address])`. Useful when you only deliver emails through one interface, but you have dual stack. For a detailed explanation, see [this issue](https://gitea.ksol.io/karolyi/py3-validate-email/issues/94).
None of the requested checks failed, but at least one of them yielded an ambiguous result. Currently, the SMTP check is the only check which can actually yield an ambiguous result.
The function `validate_email_or_fail()` works exactly like `validate_email()`, except that it raises an exception in the case of validation failure and ambiguous result instead of returning `False` or `None`, respectively.
All these exceptions descend from `EmailValidationError`. Please see below for the exact exceptions raised by the various checks. Note that all exception classes are defined in the module `validate_email.exceptions`.
Please note that `SMTPTemporaryError` indicates an ambiguous check result rather than a check failure, so if you use `validate_email_or_fail()`, you probably want to catch this exception.
By default, all checks are enabled, but each of them can be disabled by one of the `check_...` parameters. Note that, however, `check_smtp` implies `check_dns`.
Check whether the domain part of the given email address (the part behind the "@" is known as a disposable and temporary email address domain. These are often used to register dummy users in order to spam or abuse some services.
Check whether there is a valid list of servers responsible for delivering emails to the given email address.
First, a DNS query is issued for the email address' domain to retrieve a list of all MX records. That list is then stripped of duplicates and malformatted entries. If at the end of this procedure, at least one valid MX record remains, the check is considered successful.
Check whether the given email address exists by simulating an actual email delivery.
A connection to the SMTP server identified through the domain's MX record is established, and an SMTP conversation is initiated up to the point where the server confirms the existence of the email address. After that, instead of actually sending an email, the conversation is cancelled.
Unless you set `smtp_skip_tls` to `True`, the module will try to negotiate a TLS connection with STARTTLS, and silently fall back to an unencrypted SMTP connection if the server doesn't support it. Additionally, depending on your client configuration, the TLS negotiation might fail which will result in an ambiguous response for the given host as the module will be unable to communicate with the host after the negotiation fails. In trying to succeed, you can pass an `SSLContext` as an `smtp_tls_context` parameter, but remember that the server might still deny the negotiation based on how you set the `SSLContext` up, and based on its security settings as well.
If the SMTP server cannot be connected, unexpectedly closes the connection, or replies with a code `4xx` (temporary error) at any stage of the conversation, the check is considered ambiguous.
If there is more than one valid MX record for the domain, they are tried in order of priority until the first time the check is either successful or failed. Only in case of an ambiguous check result, the next server is tried, and only if the check result is ambiguous for all servers, the overall check is considered ambiguous as well.
On failure of this check or on ambiguous result, `validate_email_or_fail()` raises one of the following exceptions, all of which descend from `SMTPError`:
The SMTP server permanently refused the email address. Technically, this means that the server replied to the `RCPT TO` command with a code 5xx response.
The SMTP server refused to even let us get to the point where we could ask it about the email address. Technically, this means that the server sent a code `5xx` response either immediately after connection, or as a reply to the `EHLO` (or `HELO`) or `MAIL FROM` commands.
A temporary error occured during the check for all available MX servers. This is considered an ambiguous check result. For example, greylisting is a frequent cause for this. Make sure you check the contents of the message.
The package contains an auto-updater for downloading and updating the built-in blacklist.txt. It will run on each module load (and installation), but will try to update the content only if the file is older than 5 days, and if the content is not the same that's already downloaded.
The update can be triggered manually:
from validate_email.updater import update_builtin_blacklist
`background`: starts the update in a `Thread` so it won't make your code hang while it's updating. If you set this to `True`, the function will return the Thread used for starting the update so you can `join()` it if necessary.