Mail Configuration documentation for the dotCMS Content Management System

To configure the SMTP server to be used by dotCMS when sending emails the following needs to be updated in the context.xml file (/dotserver/tomcat-X.xx/webapps/ROOT/META-INF/context.xml).

Notes:

• It is strongly recommended that all updates to the context.xml file be done via a ROOT plugin.
• Many external mail providers, including those documented here, will require that your server has a properly-configured hostname.
  • Please consult your operating system documentation for the correct method to do this.

• Common Properties
  • Required Properties
  • SMTP Host Name
  • Authentication
  • SSL
• Examples
  • Amazon SES
  • Gmail
    • Gmail Two-Step Verification

Common Properties

Required Properties

The name, auth, and type properties included in the default configuration are required for mail to work within dotCMS, and should not be changed.

    name="mail/MailSession"
    auth="Container"
    type="javax.mail.Session"

SMTP Host Name

By default dotCMS defines the SMTP server as localhost:

    mail.smtp.host="localhost"

You must change the mail.smtp.host property to use the hostname or IP address of your SMTP server.

Authentication

If the SMTP server requires authentication, the following properties should be added:

   mail.smtp.user="username"
   password="password"

SSL

If you need to authenticate via SSL, add the following property to the configuration:

   mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"

Examples

The following examples provide configurations which have been tested and verified working for both Amazon SES and Gmail. In both examples, the mail.smtp.user and password parameters must be replaced with appropriate values (and please see the note below if you are using Two-Step Verification with your Gmail account). All other parameters should be used as they are provided in the examples.

Amazon SES

The following is an example of a mail configuration for Amazon's Simple Email Service (SES):

<Resource
   name="mail/MailSession"
   auth="Container"
   type="javax.mail.Session"
   mail.debug="true"
   mail.transport.protocol="smtp"
   mail.smtp.host="email-smtp.us-east-1.amazonaws.com"
   mail.smtp.auth="true"
   mail.smtp.port="587"
   mail.smtp.starttls.enable="true"
   mail.smtp.user="username"
   password="password"     
  />

Gmail

The following configuration includes appropriate settings to use a Gmail account:

<Resource
    name="mail/MailSession"
    auth="Container"
    type="javax.mail.Session"
    mail.smtp.host="smtp.gmail.com"
    mail.smtp.port="587"
    mail.smtp.auth="true"
    mail.smtp.starttls.enable="true"
    mail.smtp.user="user@gmail.com"
    password="password"
/>

Gmail Two-Step Verification

Important:

If your Gmail account has 2-step verification enabled, you will not be able to use your normal account password for sending email through dotCMS, and will need to create an App Password specifically for dotCMS. For more information, please see the Gmail documentation.