public class Mail
extends java.lang.Object
Mail object describes an email that will be sent automatically by the  Smart GWT
 Server as part of a normal DataSource operation.
 This class is not meant to be created and used, it is actually documentation of settings
 allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and
 above.
 See com.smartgwt.client.docs.serverds for how to use this documentation.
 
 Mail definitions are part of an OperationBinding, and
 they can only be specified in a  DataSource's XML definition.  Despite the declarative nature
 of mail definitions, templating support via Velocity makes it very flexible; it is very easy to
 include values from records just fetched from permanent storage by this operation, for example.
 See  VelocitySupport for an overview of Smart GWT Server's
 pervasive support for  templated declarative operations using Velocity.  
The default context for the message is the dsResponse.data; that is, $foo in the message refers to the field "foo" in the DataSource response (the equivalent of calling dsResponse.getFieldValue("foo") in Java). You also have access to the normal Velocity variables described in the overview linked to above.
If multiple records appear in the dsResponse, one message will be sent per record in the response unless "multiple" is set to false. This allows a set of recipients to be selected by a "fetch" operationBinding and messages sent to each. This also means that if no data is selected by a fetch or affected by an update, no mail is sent.
 If you have the Transaction Chaining feature (available  in Power
 and better versions), all of the variables normally accessible in other Velocity  contexts are
 available in the message template as well, for example: 
 $responseData.last('order').orderId 
 You can provide the body of the email
 directly in the messageTemplate
 tag, or you can provide a filename in the templateFile attribute, which tells Smart
 GWT to use the contents of that file as the body of the email.  If you  provide neither of
 these, your email will have no body; if you provide both, Smart GWT will ignore the file and
 just use the content directly provided. 
 Mail server configuration in
 server.properties
 
 Static mail server to use for sending emails can be configured in
 the server.properties file.  The following
 values can be provided:
 mail.system.mail.smtp.host: The name of the SMTP server
 to use; defaults  to "localhost"
 mail.system.mail.smtp.port: What port is the
 MTA listening on; defaults to 25
 mail.system.mail.smtp.auth: Whether this
 server requires authentication;  defaults to false
 mail.system.mail.smtp.user:
 SMTP user, if authentication is on; no default
 mail.system.mail.smtp.password:
 Password, if authentication is on; no default
 
 Note that we will also pass any other
 properties that start mail.system through to the underlying Javamail
 Session object, so you can use Javamail features that aren't explicitly exposed by
 Smart GWT's mail support.  For example, many cloud-based SMTP providers require that you issue
 a STARTTLS command before authenticating; you can  achieve this by adding the following line to
 server.properties:
 mail.system.mail.smtp.starttls.enable: true 
 Mail server configuration in
 OperationBinding
 
 Dynamic mail server can be configured in DataSource.operationBindings
 under  <mail> tag. This
 allows to alter mail server settings for different operations and depending on data using
 Velocity templates. Same values can be
 provided as in server.properties omitting "mail.system.mail.smtp" prefix, i.e.
 "host", "port", "auth", "user" and "password". 
 Just like in server.properties
 any other properties can be provided and will be passed through to the underlying Javamail
 Session object. Note that property names must omit "mail.smtp" prefix, for
 example:
 <starttls.enable>true</starttls.enable>
| Modifier and Type | Field and Description | 
|---|---|
| VelocityExpression | authDefines whether authentication is required by SMTP server that will send the email. | 
| VelocityExpression | bccComma-separated list of "BCC" recipients. | 
| VelocityExpression | ccComma-separated list of "CC" recipients. | 
| java.lang.String | contentTypeUsed to override the content-type header applied to the email. | 
| java.lang.String | encodingUsed to override the character encoding we apply to the email body. | 
| VelocityExpression | fromThe email address the message will appear to come from. | 
| VelocityExpression | hostHost of the SMTP server that will send the email. | 
| VelocityExpression | messageDataAllows you to specify an alternative source of substitution values for the templating 
  process (by default, the data record(s) returned by the DataSource operation are used). | 
| VelocityExpression | messageTemplateThe text that will form the body of the mail message. | 
| java.lang.Boolean | multipleBy default, multiple mail messages are sent if the dsResponse contains multiple records. | 
| VelocityExpression | passwordPassword if authentication is required by SMTP server that will send the email. | 
| VelocityExpression | portPort of the SMTP server that will send the email. | 
| VelocityExpression | replyToAn email address to indicate as the reply-to address on the message. | 
| VelocityExpression | subjectThe string to appear in the subject line of the message. | 
| VelocityExpression | templateFileQualified name of the file containing the message template, relative to webroot. | 
| VelocityExpression | toComma-separated list of recipients. | 
| VelocityExpression | userUser if authentication is required by SMTP server that will send the email. | 
| Constructor and Description | 
|---|
| Mail() | 
public VelocityExpression messageTemplate
String 
 properties of Mail, you can use Velocity substitution variables in this property.
  You must specify either this property or templateFile, but clearly it makes no
 sense to specify them both.
 
Default value is null
public VelocityExpression subject
String 
 properties of Mail, you can use Velocity substitution variables in this property.
 If you specify a "Subject:" line in the body of your email, the subject will be parsed and this property will be ignored.
Default value is null
public VelocityExpression to
String  properties of
 Mail, you can use Velocity substitution variables in this property. If you specify a "To:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.
Default value is null
public VelocityExpression auth
String properties of Mail, you can use Velocity substitution
 variables in this property.
 Default value is null
public VelocityExpression messageData
VelocityExpression should evaluate to a Java
 Map
  object, or a Java List containing only Maps.
  
  For example, assuming you had suitable context stored in a Map that is
  held in the current session as attribute "foo", the following would cause the mail 
  templating system to look in there for values when running substitution:
  
      messageData="$session.foo"
  
 Default value is null
public java.lang.String encoding
server.properties setting  mail.system.default.encoding, which is set to "UTF-8"
 by default.  This setting should be appropriate for most use cases.
 Default value is null
public VelocityExpression port
String
 properties of Mail, you can use Velocity substitution variables in this property.
 Default value is null
public VelocityExpression from
String 
 properties of Mail, you can use Velocity substitution variables in this property.
 If you specify a "From:" line in the body of your email, the from address will be parsed and this property will be ignored.
 Ordinarily, this property (or the parsed equivalent in
 the email body) is mandatory for all emails.  However, if you specify the property
 mail.system.mail.smtp.from in  server.properties, it will become the
 default "from" address, and this property becomes optional.
 
Default value is null
public VelocityExpression templateFile
VelocityExpression properties of Mail, you can use Velocity
 substitution variables in this property.  The content itself (ie, the contents of the file
 named in this property) can also contain Velocity substitutions, of course.  You must
 specify either this property or messageTemplate, but clearly it makes no sense to specify them both.
 
Default value is null
public java.lang.String contentType
Default value is null
public VelocityExpression host
String
 properties of Mail, you can use Velocity substitution variables in this property.
 Default value is null
public VelocityExpression user
String properties of Mail, you can use Velocity substitution
 variables in this property.
 Default value is null
public VelocityExpression replyTo
String properties of Mail, you can use Velocity substitution 
 variables in this property.
 Default value is null
public VelocityExpression bcc
String  properties of
 Mail, you can use Velocity substitution variables in this property. If you specify a "Bcc:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.
Default value is null
public VelocityExpression password
String properties of Mail, you can use Velocity substitution
 variables in this property.
 Default value is null
public VelocityExpression cc
String  properties of
 Mail, you can use Velocity substitution variables in this property. If you specify a "Cc:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.
Default value is null
public java.lang.Boolean multiple
Default value is null