When a webmaster attempts to add/change a user email, the new user email is checked to ensure it meets the user email acceptability criteria regarding length and acceptable required characters.
You may change the value for the user email acceptance criteria by overriding the dotcms.use.regex.to.validate.emails property in the (/webapps/ROOT/WEB-INF/classes/dotmarketing-config.properties) file. Overriding this should be achieved via Configuration Plugin.
Validation Parameters
The following parameters configure how new user emails are validated. These parameters determine what constitutes a valid user email (e.g. what user emails the system will reject when a user attempts to save a new, non-compliant user email) and what message is displayed to a user when they enter a user email that doesn't meet the minimum requirements.
Regular Expression Validation
User emails are validated by checking to see if the user email matches the value of a regular expression you specify. All new user emails created must match the specified regular expression before the new user email will be saved. To change the regular expression used to validate user emails, modify the dotcms.use.regex.to.validate.emails property. By default, allow the following special characters:
The local-part of the email address may use any of these ASCII characters:
° uppercase and lowercase Latin letters A to Z and a to z;
° digits 0 to 9;
° special characters !#$%&'*+-/=?^_`{|}~;
° dot ., provided that it is not the first or last character unless quoted, and provided also that it does not appear consecutively unless quoted (e.g. John..Doe@example.com is not allowed but "John..Doe"@example.com is allowed);
° space and "(),:;<>@[] characters are allowed with restrictions (they are only allowed inside a quoted string, as described in the paragraph below, and in addition, a backslash or double-quote must be preceded by a backslash);
Notes:
- If the regular expression used for validation is changed, then you should also change the Validation Message (used to notify users when a new user email doesn't match the regular expression).
- ““\” is replaced with “\\” to work in Java.
- For more information on how to use regular expressions, please see the Java regular expression class documentation.
Default Validation
By default, the regex pattern for user email validation is set to the following:
dotcms.use.regex.to.validate.emails=^[a-zA-Z0-9_!#$%&'*+/=?`{|}~^.-]+@[a-zA-Z0-9.-]+$
The default value can be overridden by adding the dotcms.use.regex.to.validate.emails property to the dotmarketing-config.properties file via Configuration Plugin.
Validation Message
When a user's choice for a user email is rejected, a message is displayed informing them of the minimum user email requirements. If you change the regular expression used to validate user emails, you must also change the validation error message to match the new regular expression requirements, or the message received by the user will be incorrect.
The user email validation message is specified in the Language.properties (/webapps/ROOT/WEB-INF/messages/Language.properties) file via the please-enter-a-valid-email-address property:
please-enter-a-valid-email-address=Please enter a valid Email Address.
This property specifies the name of a language property which is specified in the language properties files (in /webapps/ROOT/WEB-INF/messages/). You should change the value of the listed language property in the Language.properties file to match the changes you've made to the Regular Expression Validation property.
Multilingual Support
In addition to the Language.properties file (/webapps/ROOT/WEB-INF/messages/Language.properties), if you wish to support additional languages on the dotCMS backend, you must also change the value of the validation message language property in the language properties files for the additional languages you wish to support. For example, if you wish to support Spanish on your site backend, you must also add or change the value of the please-enter-a-valid-email-address property in the Language-es.properties file.
Note: It is strongly recommended that all changes to the language properties files be made via a Root folder plugin.
Notes
- Changes to the user email Validation parameter (
dotcms.use.regex.to.validate.emails) will only be applied to new user emails.- When user email validation rules are changed, users with existing user emails will not be forced to change their user emails to conform to new requirements.
