1 files changed, 38 insertions, 0 deletions
diff --git a/docs/_posts/2016-12-05-v2.0-email-domain-name-validation.md b/docs/_posts/2016-12-05-v2.0-email-domain-name-validation.md
new file mode 100644
index 000000000..1794ad77a
--- /dev/null
+++ b/docs/_posts/2016-12-05-v2.0-email-domain-name-validation.md
@@ -0,0 +1,38 @@
+---
+layout: post
+title: Version 2.0 – email validation
+author: matthew
+---
+
+When someone enters an email address on FixMyStreet, we try and do some simple
+validation before sending a confirmation email, to catch typos and the like. We
+do the following:
+
+* Check the address is correctly formed (e.g. that it contains an @ sign and a
+  domain, and doesn't include irregular characters, etc);
+* Check that the email address's domain is a valid top-level domain (TLD) (it's
+  not going to be delivered anywhere if it's not); and
+* Check that the email address's domain has a valid DNS entry (so we'll be
+  able to try and deliver an email there).
+
+The middle point means using a Perl module,
+[Net::Domain::TLD](https://metacpan.org/pod/Net::Domain::TLD), that contains a
+list of all valid TLDs. This list has grown since we last updated it, and we
+found ourselves incorrectly rejecting an email address that was perfectly valid
+(a @domain.cymru address). It was at least easy to update our version of
+Net::Domain::TLD to ensure that our list of top-level domains is current.
+
+## Changing your email address
+
+The confirmation email is itself another form of validation, and the only one
+that can actually confirm that the user entering the email address has access
+to that email inbox.
+
+Version 2 of FixMyStreet now allows users to change their own email address,
+which threw up a complication – we can’t update the user’s table to their new
+email address until it’s been confirmed.
+
+So we have to store their old email address with the token that is sent to the
+new one. When the new address has been confirmed, we deal with it differently
+depending on whether or not that address already exists in the database. If it
+does, it's a matter of merging the two accounts.