Are there characters that should be avoided in the SMTP password? If so, the documentation might mention that.
My initial password did not work, and resulted in an error. I changed the password (by editing app.yml) and then rebuilt the app. After that I was able to receive the “Confirm your new account” email.
The suspect character in the original email was: ]
For the new password, I let Mailgun generate it for me.
Hi Ted! Welcome to our community! 
Special characters like ] are likely best avoided. But given Jay’s reply above I would have thought it would work, just like including % works.
Did you have quotes in your password, perchance? I think " is one that is impossible to use because it encloses the password, unless you edit app.yml to add an escape \.
If that isn’t the answer, then likely yes we need to update this documentation topic to indicate which special characters to avoid! Or update the installer to add a warning?
Without looking more carefully, I’d say change the password to not have funky characters or edit app.yml by hand and enclose the password in single quotes. discourse-setup is a fairly crude tool that’s not designed for all situations.
That’s what I would recommend. That little hiccup probably added 30 minutes to my install.
Better yet: Add password validation to the install to reject passwords that don’t meet the criteria.
I updated the OP to explicitly note that the password cannot include special characters. Is this about right?
Let’s work on incorporating any other advice into the guide and delete all these replies. Scrolling through I am not clear on many of them. For instance, the very first reply suggests that a rebuild was needed after updating the SMTP settings which contradicts the guide.
Docs improvement suggestion:
When configuring SMTP with an external provider (I was using SendGrid) I was not receiving registration emails. Running discourse-doctor identified the error: Reason: 550 The from address does not match a verified Sender Identity.
While I had the top level domain (example.com) authenticated for sending in SendGrid, I had not yet authenticated the discourse subdomain (discourse.example.com) and so SendGrid was rejecting the API calls.
While this only took me 15 minutes or so to figure out, I feel it would be helpful to include an additional comment in app.yml and the install script that makes this clearer to reduce friction for new users installing Discourse in future. Also a direct reference to the troubleshooting page would be helpful.
Something like:
# Most SMTP providers will require an authenticated domain or authenticated email
# address to send emails. Please ensure you have authenticated your sending domain
# (example.com) , sub-domain (discourse.example.com) and the `notifications` email
# address with your SMTP provider before registering new users to ensure email deliverability.
#
# The `discourse-doctor` command can assist with testing your email configuration.
# See: https://meta.discourse.org/t/troubleshoot-email-on-a-new-discourse-install