js.email.javamail.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of js-javamail Show documentation
Reference implementation of j(s)-email API base on JavaMail.
The newest version!
/**
 * Reference implementation of simple sender for email messages based on templates. This package is a thin adapter for
 * JavaMail implementation dealing only with email send; for complete mail functionality applications should use
 * JavaMail directly.
 * 
 * Email object contains the content and is based on a X(HT)ML Template that contain operators used to inject dynamic
 * content.
 * 
 * 
 *  <html>
 *      <body>
 *          <h3>Dear <span data-text="name"></span>,</h3>
 *          <p>Your account name is <span data-text="account"></span>.</h3>
 *          . . .
 *      </body>
 *  </html>
 * 
 * 
 * Using this package is straightforward: obtain new email instance from email sender - need to know template name, set
 * specific fields and send. On send gives object data containing dynamic content; in sample code user
 * instance has a field name that is injected into body/h3/span element and
 * account into body/p/span from above email template.
 * 
 *  * class User
 * {
 *   private String name;
 *   private String account;
 *   private String emailAddr;
 * }
 * 
 * EmailSender sender = Classes.getService(EmailSender.class);
 * . . .
 * sender.getEmail("user-registration").subject("user registration").to(user.getEmailAddr()).send(user);
 * 
 * 
 * Note that email instance is not reusable; create a new instance for every delivery.
 * 
 * If need to set many email properties, like long list CC and BCC it is convenient to use email model base class.
 * 
 * 
 * class UserEmail extends EmailModel
 * {
 *   public UserEmail(User user)
 *   {
 *     super(user);
 *   }
 * 
 *   public String subject()
 *   {
 *     return "user registration";
 *   }
 * 
 *   public String to()
 *   {
 *     return user.getEmailAddress();
 *   }
 * 
 *   public String cc()
 *   {
 *     return "list of comma separated email addresses";
 *   }
 * }
 * . . .
 * sender.getEmail("user-registration").send(new UserEmail(user));
 * 
 * 
 * Email Instance Fields
 * 
 * An email instance has internal fields that need to be initialized before sending; is quite common to have related
 * emails that differ on couple fields, perhaps on destination address only.
 * 

 * from - originator email address,
 * 
envelopeFrom - this is reverse path used by remote agent to send back bounce message,
 * 
to - list of email addresses for destinations,
 * 
cc - list of email addresses for copy carbon destinations,
 * 
bcc - list of email addresses for blind copy carbon destinations,
 * 
subject - email subject,
 * 
replyTo - a list of email addresses where email reply should be sent.
 * 
 * If envelopeFrom and replyTo are missing from address is used instead.
 * 
 * @author Iulian Rotaru
 * @version 1.0
 */
package js.email.javamail;