org.codemonkey.simplejavamail

Class Mailer

java.lang.Object

org.codemonkey.simplejavamail.Mailer

public class Mailer
extends Object

Mailing tool aimed for simplicity, for sending e-mails of any complexity. This includes e-mails with plain text and/or html content, embedded images and separate attachments, SMTP, SMTPS / SSL and SMTP + SSL

This mailing tool abstracts the javax.mail API to a higher level easy to use API. For public use, this tool only works with Email instances.

The e-mail message structure is built to work with all e-mail clients and has been tested with many different webclients as well as some mainstream client applications such as MS Outlook or Mozilla Thunderbird.

Technically, the resulting email structure is as follows:

 - root
        - related
                - alternative
                        - mail text
                        - mail html text
                - embedded images
        - attachments
 

Usage example:

 Email email = new Email();
 email.setFromAddress("lollypop", "lolly.pop@somemail.com");
 email.addRecipient("Sugar Cane", "sugar.cane@candystore.org", RecipientType.TO);
 email.setText("We should meet up!!");
 email.setTextHTML("<b>We should meet up!</b>");
 email.setSubject("Hey");
 new Mailer(preconfiguredMailSession).sendMail(email);
 // or:
 new Mailer("smtp.someserver.com", 25, "username", "password").sendMail(email);
 

Author:

Benny Bottema

See Also:

Mailer.MimeEmailMessageWrapper, Email

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	Mailer.MimeEmailMessageWrapper This class conveniently wraps all necessary mimemessage parts that need to be filled with content, attachments etc.

Field Summary

Fields

Modifier and Type	Field and Description
private static String	CHARACTER_ENCODING Encoding used for setting body text, email address, headers, reply-to fields etc.
private EmailAddressValidationCriteria	emailAddressValidationCriteria Email address restriction flags set either by constructor or overridden by getter by user.
private static Logger	logger
private javax.mail.Session	session Used to actually send the email.
private TransportStrategy	transportStrategy The transport protocol strategy enum that actually handles the session configuration.

Constructor Summary

Constructors

Constructor and Description
Mailer(javax.mail.Session session) Default constructor, stores the given mail session for later use.
Mailer(String host, Integer port, String username, String password) Overloaded constructor which produces a new Session on the fly, using default vanilla SMTP transport protocol.
Mailer(String host, Integer port, String username, String password, TransportStrategy transportStrategy) Overloaded constructor which produces a new Session on the fly.

Method Summary

Modifier and Type	Method and Description
void	applyProperties(Properties properties) Copies all property entries into the Session using Session.getProperties().
protected javax.mail.Session	createMailSession(String host, Integer port, String username, String password) Actually instantiates and configures the Session instance.
private javax.mail.BodyPart	getBodyPartFromDatasource(AttachmentResource resource, String dispositionType) Helper method which generates a BodyPart from an AttachmentResource (from its DataSource) and a disposition type (Part.INLINE or Part.ATTACHMENT).
javax.mail.Session	getSession() In case Simple Java Mail falls short somehow, you can get a hold of the internal Session instance to debug or tweak.
private void	logSession(javax.mail.Session session, TransportStrategy transportStrategy) Simply logs host details, credentials used and whether authentication will take place and finally the transport protocol used.
private javax.mail.Message	prepareMessage(Email email, Mailer.MimeEmailMessageWrapper messageRoot) Creates a new MimeMessage instance and prepares it in the email structure, so that it can be filled and send.
void	sendMail(Email email) Processes an Email instance into a completely configured Message.
private void	setAttachments(Email email, javax.mail.internet.MimeMultipart multipartRoot) Fills the Message instance with the attachments from the Email.
void	setDebug(boolean debug) Actually sets Session.setDebug(boolean) so that it generates debug information.
void	setEmailAddressValidationCriteria(EmailAddressValidationCriteria emailAddressValidationCriteria) Overrides the default email address validation restrictions when validating and sending emails using the current Mailer instance.
private void	setEmbeddedImages(Email email, javax.mail.internet.MimeMultipart multipartRelated) Fills the Message instance with the embedded images from the Email.
private void	setHeaders(Email email, javax.mail.Message message) Sets all headers on the Message instance.
private void	setRecipients(Email email, javax.mail.Message message) Fills the Message instance with recipients from the Email.
private void	setReplyTo(Email email, javax.mail.Message message) Fills the Message instance with reply-to address.
private void	setTexts(Email email, javax.mail.internet.MimeMultipart multipartAlternativeMessages) Fills the Message instance with the content bodies (text and html).
boolean	validate(Email email) Validates an Email instance.

Methods inherited from class java.lang.Object

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

Field Detail

logger

private static final Logger logger

CHARACTER_ENCODING

private static final String CHARACTER_ENCODING

Encoding used for setting body text, email address, headers, reply-to fields etc. ("UTF-8").

See Also:

Constant Field Values

session

private final javax.mail.Session session

Used to actually send the email. This session can come from being passed in the default constructor, or made by Mailer directly, when no Session instance was provided.

See Also:

Mailer(Session), Mailer(String, Integer, String, String, TransportStrategy)

transportStrategy

private TransportStrategy transportStrategy

The transport protocol strategy enum that actually handles the session configuration. Session configuration meaning setting the right properties for the appropriate transport type (ie. "mail.smtp.host" for SMTP, "mail.smtps.host" for SMTPS).

emailAddressValidationCriteria

private EmailAddressValidationCriteria emailAddressValidationCriteria

Email address restriction flags set either by constructor or overridden by getter by user.

See Also:

EmailAddressValidationCriteria

Constructor Detail

Mailer

public Mailer(javax.mail.Session session)

Default constructor, stores the given mail session for later use. Assumes that *all* properties used to make a connection are configured (host, port, authentication and transport protocol settings).

Also leaves email address validation criteria empty so that no validation is being performed. Validation errors will come from the smtp server instead.

Parameters:

session - A preconfigured mail Session object with which a Message can be produced.

Mailer

public Mailer(String host,
              Integer port,
              String username,
              String password,
              TransportStrategy transportStrategy)

Overloaded constructor which produces a new Session on the fly. Use this if you don't have a mail session configured in your web container, or Spring context etc.

Also leaves email address validation criteria empty so that no validation is being performed. Validation errors will come from the smtp server instead.

Parameters:

host - The address URL of the SMTP server to be used.

port - The port of the SMTP server.

username - An optional username, may be null.

password - An optional password, may be null, but only if username is null as well.

transportStrategy - The transport protocol configuration type for handling SSL or TLS (or vanilla SMTP)

Mailer

public Mailer(String host,
              Integer port,
              String username,
              String password)

Overloaded constructor which produces a new Session on the fly, using default vanilla SMTP transport protocol.

Parameters:

host - The address URL of the SMTP server to be used.

port - The port of the SMTP server.

username - An optional username, may be null.

password - An optional password, may be null, but only if username is null as well.

See Also:

Mailer(String, Integer, String, String, TransportStrategy)

Method Detail

createMailSession

protected javax.mail.Session createMailSession(String host,
                                               Integer port,
                                               String username,
                                               String password)

Actually instantiates and configures the Session instance. Delegates resolving transport protocol specific properties to the transportStrategy in two ways:

1. request an initial property list which the strategy may pre-populate
2. by requesting the property names according to the respective transport protocol it handles (for the host property for example it would be "mail.smtp.host" for SMTP and "mail.smtps.host" for SMTPS)

Parameters:

host - The address URL of the SMTP server to be used.

port - The port of the SMTP server.

username - An optional username, may be null.

password - An optional password, may be null.

Returns:

A fully configured Session instance complete with transport protocol settings.

See Also:

TransportStrategy.generateProperties(), TransportStrategy.propertyNameHost(), TransportStrategy.propertyNamePort(), TransportStrategy.propertyNameUsername(), TransportStrategy.propertyNameAuthenticate()

getSession

public javax.mail.Session getSession()

In case Simple Java Mail falls short somehow, you can get a hold of the internal Session instance to debug or tweak. Please let us know why you are needing this on https://github.com/bbottema/simple-java-mail/issues.

setDebug

public void setDebug(boolean debug)

Actually sets Session.setDebug(boolean) so that it generates debug information.

Parameters:

debug - Flag to indicate debug mode yes/no.

applyProperties

public void applyProperties(Properties properties)

Copies all property entries into the Session using Session.getProperties().

Parameters:

properties - The source properties to add or override in the internal Session instance.

sendMail

public final void sendMail(Email email)
                    throws MailException

Processes an Email instance into a completely configured Message.

Sends the Sun JavaMail Message object using Session.getTransport(). It will call Service.connect() assuming all connection details have been configured in the provided Session instance.

Performs a call to Message.saveChanges() as the Sun JavaMail API indicates it is needed to configure the message headers and providing a message id.

Parameters:

email - The information for the email to be sent.

Throws:

MailException - Can be thrown if an email isn't validating correctly, or some other problem occurs during connection, sending etc.

See Also:

validate(Email), prepareMessage(Email, MimeEmailMessageWrapper), setRecipients(Email, Message), setTexts(Email, MimeMultipart), setEmbeddedImages(Email, MimeMultipart), setAttachments(Email, MimeMultipart)

logSession

private void logSession(javax.mail.Session session,
                        TransportStrategy transportStrategy)

Simply logs host details, credentials used and whether authentication will take place and finally the transport protocol used.

validate

public boolean validate(Email email)
                 throws MailException

Validates an Email instance. Validation fails if the subject is missing, content is missing, or no recipients are defined.

Parameters:

email - The email that needs to be configured correctly.

Returns:

Always true (throws a MailException exception if validation fails).

Throws:

MailException - Is being thrown in any of the above causes.

See Also:

EmailValidationUtil

prepareMessage

private javax.mail.Message prepareMessage(Email email,
                                          Mailer.MimeEmailMessageWrapper messageRoot)
                                   throws javax.mail.MessagingException,
                                          UnsupportedEncodingException

Creates a new MimeMessage instance and prepares it in the email structure, so that it can be filled and send.

Fills subject, from,reply-to, content, sent-date, recipients, texts, embedded images, attachments, content and adds all headers.

Parameters:

email - The email message from which the subject and From-address are extracted.

messageRoot - The root of the email which holds everything (filled with some email data).

Returns:

A fully preparated Message instance, ready to be sent.

Throws:

javax.mail.MessagingException - May be thrown when the message couldn't be processed by JavaMail.

UnsupportedEncodingException - Zie InternetAddress.InternetAddress(String, String).

setRecipients

private void setRecipients(Email email,
                           javax.mail.Message message)
                    throws UnsupportedEncodingException,
                           javax.mail.MessagingException

Fills the Message instance with recipients from the Email.

Parameters:

email - The message in which the recipients are defined.

message - The javax message that needs to be filled with recipients.

Throws:

UnsupportedEncodingException - See InternetAddress.InternetAddress(String, String).

javax.mail.MessagingException - See Message.addRecipient(javax.mail.Message.RecipientType, Address)

setReplyTo

private void setReplyTo(Email email,
                        javax.mail.Message message)
                 throws UnsupportedEncodingException,
                        javax.mail.MessagingException

Fills the Message instance with reply-to address.

Parameters:

email - The message in which the recipients are defined.

message - The javax message that needs to be filled with reply-to address.

Throws:

UnsupportedEncodingException - See InternetAddress.InternetAddress(String, String).

javax.mail.MessagingException - See Message.setReplyTo(Address[])

setTexts

private void setTexts(Email email,
                      javax.mail.internet.MimeMultipart multipartAlternativeMessages)
               throws javax.mail.MessagingException

Fills the Message instance with the content bodies (text and html).

Parameters:

email - The message in which the content is defined.

multipartAlternativeMessages - See MimeMultipart.addBodyPart(BodyPart)

Throws:

javax.mail.MessagingException - See Part.setText(String), Part.setContent(Object, String) and MimeMultipart.addBodyPart(BodyPart).

setEmbeddedImages

private void setEmbeddedImages(Email email,
                               javax.mail.internet.MimeMultipart multipartRelated)
                        throws javax.mail.MessagingException

Fills the Message instance with the embedded images from the Email.

Parameters:

email - The message in which the embedded images are defined.

multipartRelated - The branch in the email structure in which we'll stuff the embedded images.

Throws:

javax.mail.MessagingException - See MimeMultipart.addBodyPart(BodyPart) and getBodyPartFromDatasource(AttachmentResource, String)

setAttachments

private void setAttachments(Email email,
                            javax.mail.internet.MimeMultipart multipartRoot)
                     throws javax.mail.MessagingException

Fills the Message instance with the attachments from the Email.

Parameters:

email - The message in which the attachments are defined.

multipartRoot - The branch in the email structure in which we'll stuff the attachments.

Throws:

javax.mail.MessagingException - See MimeMultipart.addBodyPart(BodyPart) and getBodyPartFromDatasource(AttachmentResource, String)

setHeaders

private void setHeaders(Email email,
                        javax.mail.Message message)
                 throws UnsupportedEncodingException,
                        javax.mail.MessagingException

Sets all headers on the Message instance. Since we're not using a high-level JavaMail method, the JavaMail library says we need to do some encoding and 'folding' manually, to get the value right for the headers (see MimeUtility.

Parameters:

email - The message in which the headers are defined.

message - The Message on which to set the raw, encoded and folded headers.

Throws:

UnsupportedEncodingException - See MimeUtility.encodeText(String, String, String)

javax.mail.MessagingException - See Part.addHeader(String, String)

See Also:

MimeUtility#encodeText(String, String, String)}, MimeUtility.fold(int, String)

getBodyPartFromDatasource

private javax.mail.BodyPart getBodyPartFromDatasource(AttachmentResource resource,
                                                      String dispositionType)
                                               throws javax.mail.MessagingException

Helper method which generates a BodyPart from an AttachmentResource (from its DataSource) and a disposition type (Part.INLINE or Part.ATTACHMENT). With this the attachment data can be converted into objects that fit in the email structure.

For every attachment and embedded image a header needs to be set.

Parameters:

resource - An object that describes the attachment and contains the actual content data.

dispositionType - The type of attachment, Part.INLINE or Part.ATTACHMENT .

Returns:

An object with the attachment data read for placement in the email structure.

Throws:

javax.mail.MessagingException - All BodyPart setters.

setEmailAddressValidationCriteria

public void setEmailAddressValidationCriteria(EmailAddressValidationCriteria emailAddressValidationCriteria)

Overrides the default email address validation restrictions when validating and sending emails using the current Mailer instance. By default no validation will be performed by simple-java-mail, until a criteria object has been set.

Parameters:

emailAddressValidationCriteria - Refer to EmailAddressValidationCriteria.EmailAddressValidationCriteria(boolean, boolean).