com.smartgwt.client.client.docs

## Interface Mail

-     public interface Mail

  A `Mail` object describes an email that will be sent automatically by the Smart GWT Server as part of a normal `DataSource` operation. 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, all of the variables normally accessible in other Velocity contexts are available in the message template as well, for example, $responseData.last('order').orderId. See `transaction chaining` for more details.

  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
  The mail server to use for sending emails is 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`