Rejecting `example.com` addresses

[webbnh]

Starting in v1.2.0, email-validator is rejecting example.com addresses. While this is consistent with its documented behavior,

Other Special Use Domain Names are always considered invalid and raise EmailUndeliverableError.

it would seem to violate IETF RFC 6761 section 6.5 which says :

Application software SHOULD NOT recognize example names as special and SHOULD use example names as they would other domain names.

Sadly, when our CI pulled in the new release, our testing broke, because we use example.com in our test code.

[JoshData]

Ah! Ok. I'll look over the RFC and fix it (but I can't do it immediately, I would recommend pinning to the prior version of the library for now).

[webbnh]

Thanks for the quick response!

While we can certainly put in a rev-lock, I think instead we will take this as a prompt to add proper mocking to our unit testing. 🙂 (The new release shouldn't adversely affect our functional testing or production code. 🤞)

Mostly, I wanted to raise the issue in case other people were surprised by the change as well.

[M3te0r]

Hi, I encountered the same issue with my unit test suite as I use Faker and pydantic with the EmailStr validator that itself use python-email-validator, updating today to v1.2.0 broke the validation of exemple.com/org/net... domains

[elanor-sparx]

Same issue here, use example.com all over our test code because it isn't deliverable. Would be up for changing it in the future but it's breaking almost everything right now. Will do as suggested above and pin to previous release.
Thanks for your work maintaining the package, it's much appreciated.

[JoshData]

I've pushed a commit that removes example and example.com/net/org from the special use domains list. I'll make a release later in the week.

RFC 6761 says applications "SHOULD NOT" treat the "example" domains as special, which doesn't mean it's wrong to reject them (it's not MUST NOT), but I get the problem. Since these domain names are reserved for IANA, I think it's safe for this library to accept them. (Since they are reserved for documentation, it's probably not appropriate to use these addresses generally in tests.)

In the latest release of this library, DNS-based deliverability checks will fail these domains anyway because example.com/net/org publish a NULL MX record (that's new in this release) and the subdomains (e.g. mail.example) don't resolve (that behavior is old). So beware that even with these domains removed from the special-use list, they may still fail. But with check_deliverability=False (which is probably a good idea in test environments anyway), they will now pass. ("example" alone, i.e. "josh@example", doesn't have a period which this library has always failed as a syntax error.)

The RFC says the same thing about "test," but because "test" is not reserved to IANA and the RFC warns that users should be aware that "test" may resolve differently in different environments, this domain does not seem to me to be safe to pass validation.

The latest release of this library has a new keyword argument test_environment. When it is true, DNS-based deliverabiltiy checks are disabled (same as check_deliverability=False) and "test" is removed from the special-use domains list so that it can be used in tests (e.g. "me@test" or "me@mail.test" etc.). I think giving test_environment=True and using @test email addresses is probably the right approach for creating tests, rather than using @example.com/net/org addresses. But with the latest commit, using example domains would also work.

How does this all sound?

[webbnh]

My read of RFC 6761 is that the difference between example.com (and its siblings and top-level relation) and the top-level test. domain is the point at which failures should be reported. That is, test. should be rejected at the DNS server and not be before, while example.com should not be treated specially at any level. (This is to be contrasted with invalid., which may be rejected at any level and should be rejected before being presented to the DNS.)

So, like any tool, the appropriate one should selected for the job. example.com should be used with care in functional situations, since it will potentially use non-local resources; test. is more appropriate in that scenario, since it can be resolved (negatively) locally. (The problem with using invalid. is that it might result in very little actually being tested.)

In my project's case, we're doing unit testing, so we don't expect any impact beyond the local machine. Arguably, test. would be an appropriate choice, but there shouldn't be any reason why example.com should generate failures, since we don't expect the requests to ever make it as far as DNS.

RFC 6761 says applications "SHOULD NOT" treat the "example" domains as special, which doesn't mean it's wrong to reject them (it's not MUST NOT)

"Wrong" is a tricky word, here. 🙂 RFC 2119 says that while "there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, [...] the full implications should be understood and the case carefully weighed," and I think we're in agreement that not conforming to RFC 6761 is counterproductive, at least so far as example.com is concerned. (But, I think we're in disagreement about test.....)

With respect to test_environment, unfortunately that poses a philosophical problem. The idea behind both functional and unit testing is to drive the code through it's various behaviors from the outside. Having to reach inside and change values passed to an internal function call is not consistent with that principle. It would be more appropriate if test_environment were settable via some sort of out-of-band means, like an environment variable, or a global variable, or a configuration setting addressable via a package function, etc. We shouldn't have to alter the code-under-test itself in order to test it.

How does this all sound?

Removing the special treatment of example.com covers us. I'll defer to others to fight for test., although my reading of RFC 6761 section 6.2 suggests that application software and name resolution libraries (I expect that email-validator falls into one of those two buckets...) "SHOULD NOT" recognize those names as special.

Perhaps the answer is to add another keyword or configurator which allows the application to opt-in or opt-out of having special names recognized. That is, rather than trying to figure out whether the code is in a "test environment" and trying to define behavior suitable for that, perhaps the better approach is for the caller to request the behavior that it requires. (Or, perhaps you can tie it to check_deliverability, since we can predict that neither example.com nor test. are deliverable addresses.)

In any case, thank you for your responsiveness and for email-validator!

[Cheaterman]

Here we used .local because it offers further guarantees to not only never reach the internet but also probably won't be looked up by proper DNS resolvers (mdns highjacks it).

[JoshData]

Good feedback, all. Thanks.

I just thought, a workaround here could be:

import email_validator
email_validator.SPECIAL_USE_DOMAIN_NAMES = list(email_validator.SPECIAL_USE_DOMAIN_NAMES) # convert tuple to list
email_validator.SPECIAL_USE_DOMAIN_NAMES.remove("example.com")
email_validator.SPECIAL_USE_DOMAIN_NAMES.remove("test")
email_validator.SPECIAL_USE_DOMAIN_NAMES.remove("local")

This should work in the released version, and I would be glad to make this a documented capability (and change it to a list rather than a tuple). This would be in addition to removing the example domains from the list but instead of removing test or local from the list (i.e. I would intend to keep them in the list and allow users to remove them this way).

(Also am happy to consider adding other global options.)

My main concern here is keeping applications safe, and I strongly think that allowing domains with undefined and non-global behavior (local, test) is not safe, especially local which if it resolves at all definitely would not be safe in a production environment.

[webbnh]

@JoshData, that's definitely a plausible approach.

However, to me, that feels like reaching inside what should be an opaque object and messing with its guts, but that's probably my own problem -- I come from a mindset where a package interface should be functional, and package data should be readonly, immutable, or hidden. Now, I know that that's not really feasible in Python (and I note that SPECIAL_USE_DOMAIN_NAMES does not begin with an underscore...but I don't consider that lack as positive permission to modify it in production code!)

So, if you want to document SPECIAL_USE_DOMAIN_NAMES as a mutable and part of the package interface, that's fine...but I personally would prefer an API function for getting and/or setting it. But, as I say, that's just me.... 😉

[Cheaterman]

I'm with @webbnh on this, but I'd go slightly further... I understand that this came with the best intentions, but you know how the saying goes :-) I think this feature should be opt-in rather than opt-out in the first place, with a separate boolean flag controlling it ; this way, you give dependents time to implement their own wrappers around the new boolean flag (whether they want to support the extended "pick which domains are special" approach is probably up to them in the first place) - the reason I'm wording it that way is because (and I suppose this is common) I don't actually directly use python-email-validator but flask-wtforms, which uses wtforms, which can optionally work with python-email-validator (notice the three layers deep, relatively obscure breakage from my POV, hehe).