Mail Configuration documentation for the dotCMS Content Management System

There are two ways of configuring the SMTP server to be used by dotCMS when sending emails: By setting environment variables or by adding configuration to the context.xml file (deprecated).

• Environment Variable Configuration
  • Environment Variables Example
• Context.xml Configuration (Deprecated)
  • Context.xml Example: Amazon SES
  • Context.xml Example: Gmail
• Multi-Factor Authentication

Environment Variable Configuration

You can configure the SMTP server dotCMS will use by setting environment variables.

Environment Variables Example

You can use environment variables to configure SMTP service to be used by dotCMS when sending emails. Below is an example of the environment variables that need to be set:

DOT_MAIL_SMTP_HOST: {smtpserver.customer.com}
DOT_MAIL_SMTP_USER: {SMTP user/Access key ID}
DOT_MAIL_SMTP_PASSWORD: {SMTP Access password/secret key}
DOT_MAIL_SMTP_PORT: 587
DOT_MAIL_SMTP_AUTH: true
DOT_MAIL_SMTP_STARTTLS_ENABLE: true
DOT_MAIL_SMTP_SSL_PROTOCOLS: TLSv1.2

Context.xml Configuration (Deprecated)

To configure the SMTP server information in the context.xml file in the /dotserver/tomcat-X.xx/webapps/ROOT/META-INF folder in the dotCMS distribution. Note: It is strongly recommended that changes to the context.xml file be performed using the configuration plugin.

The following examples for Amazon SES and Gmail configure dotCMS to use SMTP via the JNDI service mail/MailSession. 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.

Context.xml Example: Amazon SES

The following is an example 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"     
  />

Context.xml Example: 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"
/>

Multi-Factor Authentication

Important:

If your email provider has multi-factor authentication enabled (for example, Gmail 2-step verification), then you willmay not be able to use your normal account password for sending email through dotCMS.

For example, if you have Gmail 2-step verification enabled, then you'll need to create an App Password specifically for dotCMS.

For more information on working with Gmail 2-step verification, please see the Gmail documentation. For more information on other email providers, please see the email provider documentation.