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:

MimeEmailMessageWrapper, Email

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.
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.
void	sendMail(Email email) Processes an Email instance into a completely configured Message.
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.
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

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)

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

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).