com.isomorphic.mail

## Class MailMessage

- java.lang.Object
- - com.isomorphic.base.Base
  - - com.isomorphic.mail.MailMessage

- Direct Known Subclasses:
    TemplatedMailMessage

      public class MailMessage
      extends Base

  This class contains methods for creating and sending an email message.

  There are two general approaches to doing this. Here is the first one:

  ``

       MailMessage message = new MailMessage();
       message.setFrom("me@my.address");
       message.addRecipients("friend1@his.address, friend2@her.address");
       message.setSubject("Greetings");
       message.setBody("Hello everyone!");
       message.send();

  Here is the second approach:

  ``

       MailMessage message = new MailMessage();
       message.parse("From: me@my.address\n"
                   + "To: friend1@his.address, friend2@her.address\n"
                   + "Subject: Greetings\n"
                   + "Hello everyone!\n");
       message.send();

  You may mix and match the two approaches as desired. For example, you could use the `parse` method, then the `addRecipient` method.

  Note: You must add your mail subsystem information to your `server.properties` file. An example follows:

  `#=======================================================
  # Mail subsystem
  #=======================================================
  # Comma-delimited list of all smtp servers capable of
  # relaying mail to the internet
  mail.system.mail.smtp.host: mail
  # What port is the MTA listening on
  mail.system.mail.smtp.port: 25
  # Number of milliseconds to socket connet timeout. When
  # this limit is reached, we try the next mail server.
  mail.system.mail.smtp.connectiontimeout: 2000
  # Base mail template directory
  mail.templateRoot: $webRoot/config/mailTemplates
  # What email account to use when the system sends out
  # mails
  mail.systemFromAddress: website@companyName.com
  mail.helpdeskAddress: support@companyName.com
  mail.URLPrefix: http://www.companyName.com
  `

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addHeader(java.lang.String field, java.lang.String value)` Adds a header to the email.
    `void` | `addHeaders(java.util.Map headers)` Adds a set of headers to the email.
    `void` | `addRecipient(java.lang.String recipient)` Adds a recipient to the email.
    `void` | `addRecipient(java.lang.String recipient, javax.mail.Message.RecipientType type)` Adds a recipient of the specified type to the email.
    `void` | `addRecipients(java.util.List recipients)` Adds a list of recipients to the email.
    `void` | `addRecipients(java.util.List recipients, javax.mail.Message.RecipientType type)` Adds a list of recipients of the specified type to the email.
    `void` | `addRecipients(java.lang.String recipients)` Adds a comma-delimited list of recipients to the email.
    `void` | `addRecipients(java.lang.String recipients, javax.mail.Message.RecipientType type)` Adds a comma-delimited list of recipients of the specified type to the email.
    `void` | `addReplyTo(java.lang.String replyTo)` Adds a "reply to" address to the email.
    `java.io.Writer` | `getBodyWriter()` Gets the `Writer` stream for the message body.
    `void` | `reset()` Resets MailMessage state.
    `void` | `send()` Sends the email message.
    `void` | `setAuth(java.lang.String auth)` Sets if SMTP connection should be authorized.
    `void` | `setBody(java.lang.String newBody)` Adds the message body to the email.
    `void` | `setContextMap(java.util.Map value)` Sets the context map to use with this message.
    `void` | `setFrom(java.lang.String sender)` Sets the "from" address of the email.
    `void` | `setHost(java.lang.String host)` Sets SMTP host or Velocity expression.
    `void` | `setPassword(java.lang.String password)` Sets SMTP connection password or Velocity expression.
    `void` | `setPort(java.lang.String port)` Sets SMTP port or Velocity expression.
    `void` | `setProperty(java.lang.String name, java.lang.String value)` Additional property that will be passed to `Session` class.
    `void` | `setRecipient(java.lang.String recipient)` Adds a recipient to the email.
    `void` | `setReplyTo(java.util.List replyTo)` Sets the parameter list of addresses passed in as the "reply to" addresses for the email.
    `void` | `setReplyTo(java.lang.String replyTo)` Sets the "reply to" address for the email.
    `void` | `setSubject(java.lang.String subject)` Sets the subject of the email.
    `void` | `setUser(java.lang.String user)` Sets SMTP connection user or Velocity expression.

- - ### Method Detail

    - #### setContextMap

          public void setContextMap(java.util.Map value)

      Sets the context map to use with this message. Velocity looks in the context map to find its substitution values
      Parameters:
        `value` - The new context map

    - #### setFrom

          public void setFrom(java.lang.String sender)

      Sets the "from" address of the email.
      Parameters:
        `sender` - the "from" address

    - #### addReplyTo

          public void addReplyTo(java.lang.String replyTo)

      Adds a "reply to" address to the email.
      Parameters:
        `replyTo` - the "reply to" address

    - #### setReplyTo

          public void setReplyTo(java.lang.String replyTo)

      Sets the "reply to" address for the email. If the provided String contains commas, we assume that it is a comma-separated list of addresses; otherwise, it is treated as a String containing a single address
      Parameters:
        `replyTo` - the "reply to" address

    - #### setReplyTo

          public void setReplyTo(java.util.List replyTo)

      Sets the parameter list of addresses passed in as the "reply to" addresses for the email.
      Parameters:
        `replyTo` - the "reply to" address

    - #### setSubject

          public void setSubject(java.lang.String subject)

      Sets the subject of the email.
      Parameters:
        `subject` - the subject

    - #### setHost

          public void setHost(java.lang.String host)

      Sets SMTP host or Velocity expression.
      Parameters:
        `host` - host

    - #### setPort

          public void setPort(java.lang.String port)

      Sets SMTP port or Velocity expression.
      Parameters:
        `port` - integer value as `String` or Velocity expression

    - #### setAuth

          public void setAuth(java.lang.String auth)

      Sets if SMTP connection should be authorized.
      Parameters:
        `auth` - boolean value as `String` or Velocity expression

    - #### setUser

          public void setUser(java.lang.String user)

      Sets SMTP connection user or Velocity expression.
      Parameters:
        `user` - user

    - #### setPassword

          public void setPassword(java.lang.String password)

      Sets SMTP connection password or Velocity expression.
      Parameters:
        `password` - password

    - #### addHeader

          public void addHeader(java.lang.String field,
                                java.lang.String value)

      Adds a header to the email.
      Parameters:
        `field` - the name of the header
        `value` - the header value

    - #### addHeaders

          public void addHeaders(java.util.Map headers)

      Adds a set of headers to the email.
      Parameters:
        `headers` - the set of headers to be added

    - #### addRecipient

          public void addRecipient(java.lang.String recipient)

      Adds a recipient to the email.
      Parameters:
        `recipient` - the email address of the recipient

    - #### setRecipient

          public void setRecipient(java.lang.String recipient)

      Adds a recipient to the email. This method here for DataTools.setProperties() style interaction.
      Parameters:
        `recipient` - the email address of the recipient

    - #### addRecipients

          public void addRecipients(java.util.List recipients)

      Adds a list of recipients to the email.
      Parameters:
        `recipients` - the list of email addresses of the recipients

    - #### addRecipients

          public void addRecipients(java.lang.String recipients)

      Adds a comma-delimited list of recipients to the email.
      Parameters:
        `recipients` - the comma-delimited list of email addresses of the recipients

    - #### addRecipient

          public void addRecipient(java.lang.String recipient,
                                   javax.mail.Message.RecipientType type)

      Adds a recipient of the specified type to the email.
      Parameters:
        `recipient` - the email address of the recipient
        `type` - the type of recipient, for example, `Message.RecipientType.TO`

    - #### addRecipients

          public void addRecipients(java.util.List recipients,
                                    javax.mail.Message.RecipientType type)

      Adds a list of recipients of the specified type to the email.
      Parameters:
        `recipients` - the list of email addresses of the recipients
        `type` - the type of the recipientsfor example, `Message.RecipientType.TO`

    - #### addRecipients

          public void addRecipients(java.lang.String recipients,
                                    javax.mail.Message.RecipientType type)

      Adds a comma-delimited list of recipients of the specified type to the email.
      Parameters:
        `recipients` - the comma-delimited list of email addresses of the recipients
        `type` - the types of the recipients for example, `Message.RecipientType.TO`

    - #### setBody

          public void setBody(java.lang.String newBody)

      Adds the message body to the email.
      Parameters:
        `newBody` - the message body

    - #### setProperty

          public void setProperty(java.lang.String name,
                                  java.lang.String value)

      Additional property that will be passed to `Session` class. All properties set via `setProperty` will override properties set by dedicated setters like `setHost(...)` and any related properties configured in `server.properties`.

      Note, that property values also support Velocity templates.
      Parameters:
        `name` - property name, omitting `"mail.smtp."` prefix
        `value` - property value

    - #### getBodyWriter

          public java.io.Writer getBodyWriter()

      Gets the `Writer` stream for the message body.
      Returns:
        the `Writer` stream for the message body

    - #### send

          public void send()
                    throws java.lang.Exception

      Sends the email message.
      Throws:
        `java.io.IOException` - if an I/O error occurs while trying to send the email
        `java.lang.Exception`

    - #### reset

          public void reset()

      Resets MailMessage state.