All about emails and how they're used in NodeBB

NodeBB Development
  • We've been seeing a steady flow of inquiries regarding how NodeBB handles emails. I will try to head off these inquiries and at the same time, provide a central point of support for people who have questions regarding how email addresses work in NodeBB.

    I'll start by stating upfront that I will divide this post into two parts — a high-level review of email handling changes, and a more technical half that details how these changes affect developers on the back end.

    Secondly, I will also note that these changes have been in v1.18.0, so there is nothing new here for v3.x.

    High Level Overview

    NodeBB makes several assumptions:

    1. An email is not an integral part of the user account
    2. NodeBB by default will ask you for an email, but it is optional. You can put a fake email in, or even nothing at all.
    3. However — an email is not truly associated with a user until the user has confirmed their email by clicking on the unique URL in the welcome/confirmation email.
      • Likewise, if an account's email is changed, it is merely a request to change the email. The old email remains until the new email is confirmed.

    Email is not integral to the user; you can put in any email address if prompted

    We wanted the flexibility of not requiring an email address for a user account.

    Part of that is because validating the format of an email is tricky. If you use even a slightly obscure email, you'll have run up against issues registering on some sites that use an incomplete format check.

    The second part of it is that if someone really wanted to not put their email down, they would just put something fake in, e.g. [email protected]. If this happens, the best case scenario is you get emails bounced back. Worse case scenario, the fake email entered actually belongs to someone else and they mark the sender (e.g. you) as spam; which leads me to the third part.

    The third part is far too many websites let users register, and allow users put in whatever email they want, even if it belongs to someone else. I refuse to allow NodeBB to become part of this unintentional spam.

    The only checking we will ever do on the entered email is to make sure that it contains an @ symbol. All emails contain the @ symbol.

    Aside: I have a rather common email, and I receive many emails from other people named Julian Lam, from around the world. I suppose if I ever go to Planet Fitness in the United States, I have a membership, or I can provide proof that I've ridden the bus in Cardiff, Wales. I'm also on the mailing list for a BMW dealership in Hong Kong, and haven't been able to get off of it. All the same, I'd rather not get these emails 😄

    An email is not truly part of the user until it is confirmed

    This is the sticking point that gets people confused — just because a user put in an email address, doesn't mean it's their email address. NodeBB will only make this assumption if explicitly instructed to (see technical overview). Otherwise, it will send out a validation email and add the email to the user account only when properly confirmed via unique code/link.

    Until then, the existing email is still active, or if there is no email, then the user account continues with no email associated with that user.

    Remember, the only way to ensure that an email you have is a real email... is to send it an email, and have the user physically confirm it. Full stop.

    What if I want to restrict access to my content to verified users only?

    We've introduced two new system groups to complement the original registered-users group. The three relevant groups now are:

    • registered-users — contains all users irregardless of email confirmed state
    • verified-users — users whose email has been confirmed
    • unverified-users — users who have no email, or whose email has not yet been confirmed

    By default, a new category will allow topics and replies from the registered-users group. Remove those privileges and apply them to the verified-users group as necessary. If you want a category specifically for unconfirmed users, then apply them to the unverified-users group.

    What if I know the user's email is correct, or want to add an email to a user?

    If you are an administrator, editing the user's email via their profile will bypass the confirmation request and automatically validate their email. With great power comes great responsibility.

    Technical Overview

    • NodeBB no longer trusts the email property in the user hash, and hasn't since v1.18.0. it is now purely informative. email:uid is the source of truth for what email belongs to which user.
    • When user.create is called (either via code or by API), if email is a passed-in property, then NodeBB will try to send a confirmation email, just as if it were a regular registration.
    • There are two relevant code paths:
      1. Confirmation email is sent, and the unique link is clicked. User is sent to /confirm/:code and user.email.confirmByCode is executed, followed by user.email.confirmByUid
      2. The user email is confirmed without a code; only user.email.confirmByUid is executed (see below).
    • If you want to create a user with a confirmed email, but don't want a welcome/confirmation email sent, you will need to manually set the email into the user, and run user.email.confirmByUid:
      const emailToSet = '[email protected]';
      await user.setUserField(uid, 'email', emailToSet);
      await user.email.confirmByUid(uid);
      
    • To my knowledge, there is a single case where a user may have their email set in the user hash, but not be confirmed:
      • Users created before v1.18.0 will have an email set that may or may not be confirmed, as that was the behaviour prior to this change. I recommend you either remove the user's email, or confirm it.
      • There are no ill effects to having a user account set up like this, although they may not show up in user searches if the query is an email address.
  • @julian when I change the email address of a user as admin, it shows in ACP that the email address is confirmed. However, when I searched the previous (deleted) email address, the forum still found the user, and the user could not use their old email address to create a new user account.

    Some users want to change their email addresses but keep the second account (we allow a second account, since sometimes they need to ask private questions and do not want to be associated with their well-known account), is there any way to solve this?

  • @crazycells that sounds like a bug, when an admin updates the email of a user if it's getting automatically verified the old email should be freed up.

  • @baris I thought so. User says he cannot register again since the forum tells him that this email address is already in use.

    Additionally, when I check the old email address in ACP (Manage>Users), I can still see the username show up. Is this normal? Or is it because I can see the email address in the email change history on his profile?

    I believe it should not matter which admin does the change, right? Because I did not use "admin" with user id 1 , I used my own account with admin privilege.

  • Yeah doesn't matter which admin does it, it should free up the old email. https://github.com/NodeBB/NodeBB/issues/11259

  • 🤔 interesting...

  • julianJ julian referenced this topic on


Suggested Topics