Mail Tool documentation for the dotCMS Content Management System

The $mail Velocity viewtool allows you to send email from your Velocity code.

SMTP Server Configuration

Before you can use the Mail Tool, your dotCMS instance must be configured to send email using SMTP in the context.xml file.

Important:

  • Some SMTP servers are configured to not allow the “from” email address (in the $mail viewtool call) to be different than the logged in user (in the dotCMS mail configuration), to prevent spoofing of emails.
    • Therefore if the “from” email in the $mail call is different from the SMTP user account specified in the dotCMS mail configuration, the SMTP server must be configured to allow sending from a different email address than the login email.
  • If the SMTP server is not configured properly, the $mail viewtool may fail (and you may not receive any notification, since the SMTP server may not return any error to dotCMS).

For more information on configuring dotCMS to send mail via SMTP (including examples for configuring Amazon and Google email), please see the Mail Configuration documentation.

Usage

The $mail tool supports a single method, sendEmail, which sends an email in either HTML or plain text format in the following format:

$mailer.sendEmail( to, from, subject, body, htmlFormat )

Parameters

ParameterTypeDescription
toStringThe recipient's email address.
fromStringThe sender's email address (the email address to send the email from).
Note: Please see the SMTP Server Configuration section, above, to ensure your SMTP server is configured properly to allow sending email from the email address you specify.
subjectStringThe email Subject line.
Text only, even if the htmlFormat parameter is set to True.
bodyStringThe body of the email.
HTML may be included in the body if the htmlFormat parameter is set to True.
htmlFormatBooleanTrue if the email will be sent using HTML format, False if the email will be sent as text only.

Return Value: If the email is sent successfully the return value will be empty; otherwise it will contain an error message string.

Example

The following code demonstrates how to send an email using the Mail tool:

 #set($error = $mailer.sendEmail(
                    'them@theirdomain.com',
                    'you@yourdomain.com',
                    'The Subject',
                    'The Message',
                    false))

#if($UtilMethods.isSet($error))
    ## Custom Error Handling
#else
    <p>Your message was sent.</p>
#end

Toolbox.xml Configuration

The Mail Tool is enabled by default in dotCMS. To ensure the Mail Tool is enabled, verify that the following lines exist in your toolbox.xml file:

<tool>
    <key>mailer</key>
    <scope>application</scope>
    <class>com.dotmarketing.viewtools.MailerTool</class>
</tool>