Merge pull request #22 from ellotheth/clarify-code-preference

Clarify reasons to use a code instead of a link for email verification

pages/email-verification.md

@@ -35,9 +35,13 @@ Some email providers, including Google, allow users to specify a tag that will b
 
 One way to verify email is to send a secret code stored in the server to the user's mailbox.
 
-This approach should be preferred over using links. People are increasingly less likely to click on links, and some filters may block emails with them. Using links also limits what device the user can use to create an account (eg. the user doesn't have access to their mailbox on their phone).
+This approach has some advantages over using links:
 
-The verification code should be at least 8 digits if the code is numeric, and at least 6 digits if it's alphanumeric. You should avoid using both lowercase and uppercase letters. You may also want to remove numbers and letters that can be misread (0, O, 1, I, etc). It must be generated using a cryptographically secure random generator.
+- People are increasingly less likely to click on links.
+- Some filters may automatically classify emails with links as spam or phishing.
+- Using verification links may introduce friction if the user wants to finish the process on a device that does not have access to the verification message, or on a device that cannot open links.
+
+The verification code should be at least 8 digits if the code is numeric, and at least 6 digits if it's alphanumeric. Use a stronger code if the verification is part of a secure process, like creating a new account or changing contact information. You should avoid using both lowercase and uppercase letters. You may also want to remove numbers and letters that can be misread (0, O, 1, I, etc). It must be generated using a cryptographically secure random generator.
 
 A single verification code should be tied to a single user and email. This is especially important if you allow users to change their email address after they're sent an email. Each code should be valid for at least 15 minutes (anywhere between 1-24 hours is recommended). The code must be single-use and immediately invalidated after validation. A new verification code should be generated every time the user asks for another email/code.