Package com.isomorphic.mail

# Class MailMessage

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

All Implemented Interfaces:
  `com.isomorphic.base.IAutoConfigurable`

Direct Known Subclasses:
  `TemplatedMailMessage`

public class MailMessage extends com.isomorphic.base.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

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

- ## Method Details

  - ### setContextMap

    public void setContextMap(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(String sender)
    Sets the "from" address of the email.
    Parameters:
      `sender` - the "from" address

  - ### addReplyTo

    public void addReplyTo(String replyTo)
    Adds a "reply to" address to the email.
    Parameters:
      `replyTo` - the "reply to" address

  - ### setReplyTo

    public void setReplyTo(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(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(String subject)
    Sets the subject of the email.
    Parameters:
      `subject` - the subject

  - ### setHost

    public void setHost(String host)
    Sets SMTP host or Velocity expression.
    Parameters:
      `host` - host

  - ### setPort

    public void setPort(String port)
    Sets SMTP port or Velocity expression.
    Parameters:
      `port` - integer value as `String` or Velocity expression

  - ### setAuth

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

  - ### setUser

    public void setUser(String user)
    Sets SMTP connection user or Velocity expression.
    Parameters:
      `user` - user

  - ### setPassword

    public void setPassword(String password)
    Sets SMTP connection password or Velocity expression.
    Parameters:
      `password` - password

  - ### addHeader

    public void addHeader(String field, String value)
    Adds a header to the email.
    Parameters:
      `field` - the name of the header
      `value` - the header value

  - ### addHeaders

    public void addHeaders(Map headers)
    Adds a set of headers to the email.
    Parameters:
      `headers` - the set of headers to be added

  - ### addRecipient

    public void addRecipient(String recipient)
    Adds a recipient to the email.
    Parameters:
      `recipient` - the email address of the recipient

  - ### setRecipient

    public void setRecipient(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(List recipients)
    Adds a list of recipients to the email.
    Parameters:
      `recipients` - the list of email addresses of the recipients

  - ### addRecipients

    public void addRecipients(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(String recipient, jakarta.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(List recipients, jakarta.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(String recipients, jakarta.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(String newBody)
    Adds the message body to the email.
    Parameters:
      `newBody` - the message body

  - ### setProperty

    public void setProperty(String name, 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 Writer getBodyWriter()
    Gets the `Writer` stream for the message body.
    Returns:
      the `Writer` stream for the message body

  - ### getBodyText

    public String getBodyText()
    Returns the message body as a String. Call this after buildMessage() to get the rendered content.
    Returns:
      the message body text, or null if no body has been set

  - ### send

    public void send() throws Exception
    Sends the email message.
    Throws:
      `IOException` - if an I/O error occurs while trying to send the email
      `Exception`

  - ### reset

    public void reset()
    Resets MailMessage state.