com.smartgwt.client.docs.serverds

## Class Mail

- java.lang.Object
- - com.smartgwt.client.docs.serverds.Mail

-     public class Mail
      extends java.lang.Object

  A `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>`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `VelocityExpression` | `auth` Defines whether authentication is required by SMTP server that will send the email.
    `VelocityExpression` | `bcc` Comma-separated list of "BCC" recipients.
    `VelocityExpression` | `cc` Comma-separated list of "CC" recipients.
    `java.lang.String` | `contentType` Used to override the content-type header applied to the email.
    `java.lang.String` | `encoding` Used to override the character encoding we apply to the email body.
    `VelocityExpression` | `from` The email address the message will appear to come from.
    `VelocityExpression` | `host` Host of the SMTP server that will send the email.
    `VelocityExpression` | `messageData` Allows 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` | `messageTemplate` The text that will form the body of the mail message.
    `java.lang.Boolean` | `multiple` By default, multiple mail messages are sent if the dsResponse contains multiple records.
    `VelocityExpression` | `password` Password if authentication is required by SMTP server that will send the email.
    `VelocityExpression` | `port` Port of the SMTP server that will send the email.
    `VelocityExpression` | `replyTo` An email address to indicate as the reply-to address on the message.
    `VelocityExpression` | `subject` The string to appear in the subject line of the message.
    `VelocityExpression` | `templateFile` Qualified name of the file containing the message template, relative to webroot.
    `VelocityExpression` | `to` Comma-separated list of recipients.
    `VelocityExpression` | `user` User if authentication is required by SMTP server that will send the email.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Mail()`

  - ### Method Summary

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### messageTemplate

          public VelocityExpression messageTemplate

      The text that will form the body of the mail message. Like all other `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

    - #### subject

          public VelocityExpression subject

      The string to appear in the subject line of the message. Like all other `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

    - #### to

          public VelocityExpression to

      Comma-separated list of recipients. Like all other `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

    - #### auth

          public VelocityExpression auth

      Defines whether authentication is required by SMTP server that will send the email. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### messageData

          public VelocityExpression messageData

      Allows 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). If set, this `VelocityExpression` should evaluate to a Java `Map` object, or a Java `List` containing only `Map`s.

      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

    - #### encoding

          public java.lang.String encoding

      Used to override the character encoding we apply to the email body. If you do not set this property, it is derived from the `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

    - #### port

          public VelocityExpression port

      Port of the SMTP server that will send the email. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### from

          public VelocityExpression from

      The email address the message will appear to come from. Like all other `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

    - #### templateFile

          public VelocityExpression templateFile

      Qualified name of the file containing the message template, relative to webroot. Like all the other `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

    - #### contentType

          public java.lang.String contentType

      Used to override the content-type header applied to the email. Primarily used to send HTML emails rather than plain text ones (use "text/html" to do this).

      Default value is null

    - #### host

          public VelocityExpression host

      Host of the SMTP server that will send the email. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### user

          public VelocityExpression user

      User if authentication is required by SMTP server that will send the email. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### replyTo

          public VelocityExpression replyTo

      An email address to indicate as the reply-to address on the message. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### bcc

          public VelocityExpression bcc

      Comma-separated list of "BCC" recipients. Like all other `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

    - #### password

          public VelocityExpression password

      Password if authentication is required by SMTP server that will send the email. Like all other `String` properties of `Mail`, you can use Velocity substitution variables in this property.

      Default value is null

    - #### cc

          public VelocityExpression cc

      Comma-separated list of "CC" recipients. Like all other `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

    - #### multiple

          public java.lang.Boolean multiple

      By default, multiple mail messages are sent if the dsResponse contains multiple records. Set this property to false to prevent this behavior.

      Default value is null

  - ### Constructor Detail

    - #### Mail

          public Mail()