org.simplejavamail.mailer

Class Mailer

java.lang.Object

org.simplejavamail.mailer.Mailer

public class Mailer
extends Object

Mailing tool created exclusively using MailerBuilder, 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, custom Session object, DKIM domain signing and even authenticated SOCKS proxy support and threaded batch processing.

This mailing tool abstracts the javax.mail API to a higher level easy to use API. This tool works with Email instances but can also convert traditional MimeMessage objects to and from Email object.

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 desktop applications.

Technically, the resulting email structure is as follows:

 - mixed root
        - related
                - alternative
                        - mail tekst
                        - mail html tekst
                - embedded images
        - forwarded message
        - attachments
 

Usage example (see simplejavamail.org/features for examples):

 Email email = EmailBuilder.startingBlank()
                .from("lollypop", "[email protected]");
                .to("Sugar Cane", "[email protected]");
                .withPlainText("We should meet up!!");
                .withHTMLText("<b>We should meet up!</b>");
                .withSubject("Hey");

 MailerBuilder.usingSession(preconfiguredMailSession)
                .buildMailer()
                .sendMail(email);
 // or:
 MailerBuilder.withSMTPServer("smtp.someserver.com", 25, "username", "password")
                .buildMailer()
                .sendMail(email);
 

simplejavamail.org

On a technical note, the Mailer class is the front facade for the public API. It limits itself to preparing for sending, but the actual sending and proxy configuration is done by the internal MailSender.

See Also:

MailerBuilder, Email

Method Summary

Modifier and Type	Method and Description
static javax.mail.Session	createMailSession(org.simplejavamail.mailer.ServerConfig serverConfig, TransportStrategy transportStrategy) Instantiates and configures the Session instance.
EnumSet<org.hazlewood.connor.bottema.emailaddress.EmailAddressCriteria>	getEmailAddressCriteria()
org.simplejavamail.mailer.internal.mailsender.OperationalConfig	getOperationalConfig()
org.simplejavamail.mailer.internal.mailsender.ProxyConfig	getProxyConfig()
org.simplejavamail.mailer.ServerConfig	getServerConfig()
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.
TransportStrategy	getTransportStrategy()
void	sendMail(Email email) Delegates to sendMail(Email, boolean), with async = false.
void	sendMail(Email email, boolean async)
static javax.mail.internet.MimeMessage	signMessageWithDKIM(javax.mail.internet.MimeMessage messageToSign, Email emailContainingSigningDetails) Refer to MimeMessageHelper.signMessageWithDKIM(MimeMessage, Email)
void	testConnection() Tries to connect to the configured SMTP server, including (authenticated) proxy if set up.
boolean	validate(Email email) Validates an Email instance.

Methods inherited from class java.lang.Object

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

Method Detail

createMailSession

public static javax.mail.Session createMailSession(@Nonnull
                                                   org.simplejavamail.mailer.ServerConfig serverConfig,
                                                   @Nonnull
                                                   TransportStrategy transportStrategy)

Instantiates and configures the Session instance. Delegates resolving transport protocol specific properties to the given 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)

Furthermore adds proxy SOCKS properties if a proxy configuration was provided, overwriting any SOCKS properties already present.

Parameters:

serverConfig - Remote SMTP server details.

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

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.

getServerConfig

@Nullable
public org.simplejavamail.mailer.ServerConfig getServerConfig()

Returns:

The server connection details. Will be null in case a custom fixed Session instance is used.

getTransportStrategy

@Nullable
public TransportStrategy getTransportStrategy()

Returns:

The transport strategy to be used. Will be null in case a custom fixed Session instance is used.

getProxyConfig

@Nonnull
public org.simplejavamail.mailer.internal.mailsender.ProxyConfig getProxyConfig()

Returns:

The proxy connection details. Will be empty if no proxy is required.

getOperationalConfig

@Nonnull
public org.simplejavamail.mailer.internal.mailsender.OperationalConfig getOperationalConfig()

Returns:

The operational parameters defined using a mailer builder. Includes general things like session timeouts, debug mode, SSL config etc.

getEmailAddressCriteria

@Nonnull
public EnumSet<org.hazlewood.connor.bottema.emailaddress.EmailAddressCriteria> getEmailAddressCriteria()

Returns:

The effective validation criteria used for email validation. Returns an empty set if no validation should be done.

testConnection

public void testConnection()

Tries to connect to the configured SMTP server, including (authenticated) proxy if set up.

Note: synchronizes on the thread for sending mails so that we don't get into race condition conflicts with emails actually being sent.

sendMail

public final void sendMail(Email email)

Delegates to sendMail(Email, boolean), with async = false. This method returns only when the email has been processed by the target SMTP server.

sendMail

public final void sendMail(Email email,
                           boolean async)

See Also:

MailSender.send(Email, boolean), validate(Email)

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 or that the addresses are missing for NPM notification flags.

It also checks for illegal characters that would facilitate injection attacks:

• http://www.cakesolutions.net/teamblogs/2008/05/08/email-header-injection-security
• https://security.stackexchange.com/a/54100/110048
• https://www.owasp.org/index.php/Testing_for_IMAP/SMTP_Injection_(OTG-INPVAL-011)
• http://cwe.mitre.org/data/definitions/93.html

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:

EmailAddressValidator

signMessageWithDKIM

public static javax.mail.internet.MimeMessage signMessageWithDKIM(javax.mail.internet.MimeMessage messageToSign,
                                                                  Email emailContainingSigningDetails)

Refer to MimeMessageHelper.signMessageWithDKIM(MimeMessage, Email)