// ------------------------ Notable changes ------------------------ //
== Notable changes

Notable changes where an internal behavior changed to prevent common misconfigurations, fix bugs or simplify running {project_name}.

=== UTF-8 management in the email sender

Since this release, {project_name} adds a new option `allowutf8` for the realm SMTP configuration (*Allow UTF-8* field inside the *Email* tab in the *Realm settings* section of the Admin Console).
For more information about email configuration, see the link:{adminguide_link}#_email[Configuring email for a realm] chapter in the {adminguide_name}.

Enabling the option encodes email addresses in UTF-8 when sending them, but it depends on the SMTP server to also supports UTF-8 via the SMTPUTF8 extension.
If *Allow UTF-8* is disabled, {project_name} will encode the domain part of the email address (second part after `@`) using punycode if non-ASCII characters are used, and will reject email addresses that use non-ASCII characters in the local part.

If you have an SMTP server configured for your realm, perform the following migration after the upgrade:

* If your SMTP server supports SMTPUTF8:
. Enable the *Allow UTF-8* option.
* If your SMTP server does not support SMTPUTF8:
. Keep the *Allow UTF-8* option disabled.
. Verify that no email addresses of users have non-ASCII characters in the local part of the email address.
. Update the validation of email addresses to prevent allow non-ASCII characters in the local part of the email address, for example, by adding a regex pattern validation in the user profile for the email address field similar to `\p&#123;ASCII&#125;*@.*` with an error message similar to `Local part of the address must contain only ASCII characters`.
