Mailer (Simple Java Mail 4.4.4 API)

java.lang.Object
- org.simplejavamail.mailer.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, 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:
```
 - 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);
 
```
simplejavamail.org

On a technical note, the Mailer class is the front facade for the public API. It limits itself to creating Session objects, offering various constructors, sorting missing arguments using available properties and finally email validation. The actual sending and proxy configuration is done by the internal MailSender. Some internal api is made public through this class for uses other than directly sending emails, such as setDebug(boolean) and signMessageWithDKIM(MimeMessage, Email).
Author:

Benny Bottema

See Also:

MimeMessageHelper.MimeEmailMessageWrapper, Email

Constructor Summary

Constructors
Constructor and Description
`Mailer()` No-arg constructor that only works with properly populated config file ("simplejavamail.properties") on the classpath.
`Mailer(ServerConfig serverConfig)` Delegates to `Mailer(ServerConfig, TransportStrategy, ProxyConfig)` and populates as much as possible from the config file (proxy details, transport strategy) and otherwise defaults to `TransportStrategy.SMTP_PLAIN` and skipping proxy.
`Mailer(ServerConfig serverConfig, ProxyConfig proxyConfig)` Delegates to `Mailer(ServerConfig, TransportStrategy, ProxyConfig)` and tries to populates transport strategy from config file and otherwise defaults to `TransportStrategy.SMTP_PLAIN`.
`Mailer(ServerConfig serverConfig, TransportStrategy transportStrategy)` Delegates to `Mailer(ServerConfig, TransportStrategy, ProxyConfig)` and tries to populates proxy details from config file and otherwise skips proxy.
`Mailer(ServerConfig serverConfig, TransportStrategy transportStrategy, ProxyConfig proxyConfig)` Main constructor which produces a new `Session` on the fly.
`Mailer(javax.mail.Session session)` Custom Session constructor, stores the given mail session for later use.
`Mailer(javax.mail.Session session, ProxyConfig proxyConfig)` Custom Session constructor with proxy, stores the given mail session for later use.
`Mailer(String host, Integer port, String username, String password)` Delegates to `Mailer(ServerConfig, TransportStrategy, ProxyConfig)` and populates as much as possible from the config file (proxy details, transport strategy) and otherwise defaults to `TransportStrategy.SMTP_PLAIN` and skipping proxy.
`Mailer(String host, Integer port, String username, String password, TransportStrategy transportStrategy)` Delegates to `Mailer(ServerConfig, TransportStrategy, ProxyConfig)` and tries to populates proxy details from config file and otherwise skips proxy.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`applyProperties(Properties properties)` Copies all property entries into the `Session` using `Session.getProperties()`.
`static javax.mail.Session`	`createMailSession(ServerConfig serverConfig, TransportStrategy transportStrategy)` 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.
`boolean`	`isTransportModeLoggingOnly()`
`void`	`sendMail(Email email)` Delegates to `sendMail(Email, boolean)`, with `async = false`.
`void`	`sendMail(Email email, boolean async)`
`void`	`setDebug(boolean debug)` Calls `Session.setDebug(boolean)` so that it generates debug information.
`void`	`setEmailAddressCriteria(EnumSet<org.hazlewood.connor.bottema.emailaddress.EmailAddressCriteria> emailAddressCriteria)` Overrides the default email address validation restrictions `emailAddressCriteria` when validating and sending emails using the current `Mailer` instance.
`void`	`setSessionTimeout(int sessionTimeout)`
`void`	`setThreadPoolSize(int poolSize)`
`void`	`setTransportModeLoggingOnly(boolean transportModeLoggingOnly)` Sets the transport mode for this mail sender to logging only, which means no mail will be actually sent out.
`static javax.mail.internet.MimeMessage`	`signMessageWithDKIM(javax.mail.internet.MimeMessage message, Email email)` Refer to `MimeMessageHelper.signMessageWithDKIM(MimeMessage, Email)`
`void`	`trustAllSSLHosts(boolean trustAllHosts)` Configures the current session to trust all hosts and don't validate any SSL keys.
`void`	`trustSSLHosts(String... hosts)` Configures the current session to white list all provided hosts and don't validate SSL keys for them.
`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)
```
    Custom Session 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). Will skip proxy.
    Uses TransportStrategy.findStrategyForSession(javax.mail.Session) to determine the right connection mode based on already available properties in the Session.
    
    Parameters:
    
    session - A preconfigured mail Session object with which a Message can be produced.
    
    See Also:
    
    Mailer(Session, ProxyConfig)
  - Mailer
```
public Mailer(javax.mail.Session session,
              ProxyConfig proxyConfig)
```
    Custom Session constructor with proxy, stores the given mail session for later use. Assumes that *all* properties (except session timeouts) used to make a connection are configured (host, port, authentication and transport protocol settings).
    Only proxy settings are always added if details are provided.
    Also set javax.mail debug mode if a config file was provided for this. Uses TransportStrategy.findStrategyForSession(javax.mail.Session) to determine the right connection mode based on already available properties in the Session.
    
    Parameters:
    
    session - A preconfigured mail Session object with which a Message can be produced.
    
    proxyConfig - Remote proxy server details, if the connection should be run through a SOCKS proxy.
  - Mailer
```
public Mailer()
```
    No-arg constructor that only works with properly populated config file ("simplejavamail.properties") on the classpath.
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and populates as much as possible from the config file (smtp server details, proxy details, transport strategy) and otherwise defaults to TransportStrategy.SMTP_PLAIN and skipping proxy.
    
    See Also:
    
    Mailer(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(String host,
              Integer port,
              String username,
              String password)
```
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and populates as much as possible from the config file (proxy details, transport strategy) and otherwise defaults to TransportStrategy.SMTP_PLAIN and skipping proxy.
    
    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(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(ServerConfig serverConfig)
```
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and populates as much as possible from the config file (proxy details, transport strategy) and otherwise defaults to TransportStrategy.SMTP_PLAIN and skipping proxy.
    
    Parameters:
    
    serverConfig - Remote SMTP server details.
    
    See Also:
    
    Mailer(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(String host,
              Integer port,
              String username,
              String password,
              TransportStrategy transportStrategy)
```
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and tries to populates proxy details from config file and otherwise skips proxy.
    
    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)
    
    See Also:
    
    Mailer(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(ServerConfig serverConfig,
              TransportStrategy transportStrategy)
```
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and tries to populates proxy details from config file and otherwise skips proxy.
    
    Parameters:
    
    serverConfig - Remote SMTP server details.
    
    transportStrategy - The transport protocol configuration type for handling SSL or TLS (or vanilla SMTP)
    
    See Also:
    
    Mailer(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(ServerConfig serverConfig,
              ProxyConfig proxyConfig)
```
    Delegates to Mailer(ServerConfig, TransportStrategy, ProxyConfig) and tries to populates transport strategy from config file and otherwise defaults to TransportStrategy.SMTP_PLAIN.
    
    Parameters:
    
    serverConfig - Remote SMTP server details.
    
    proxyConfig - Remote proxy server details, if the connection should be run through a SOCKS proxy.
    
    See Also:
    
    Mailer(ServerConfig, TransportStrategy, ProxyConfig)
  - Mailer
```
public Mailer(ServerConfig serverConfig,
              TransportStrategy transportStrategy,
              ProxyConfig proxyConfig)
```
    Main 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 sets javax.mail debug mode if a config file was provided for this.
    
    Parameters:
    
    serverConfig - Remote SMTP server details.
    
    transportStrategy - The transport protocol configuration type for handling SSL or TLS (or vanilla SMTP)
    
    proxyConfig - Remote proxy server details, if the connection should be run through a SOCKS proxy.
- Method Detail
  - createMailSession
```
public static javax.mail.Session createMailSession(ServerConfig serverConfig,
                                                   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.
  - setDebug
```
public void setDebug(boolean debug)
```
    Calls Session.setDebug(boolean) so that it generates debug information. To get more information out of the underlying JavaMail framework or out of Simple Java Mail, increase logging config of your chosen logging framework (examples here).
    
    Parameters:
    
    debug - Flag to indicate debug mode yes/no.
    
    See Also:
    
    ConfigLoader.Property.JAVAXMAIL_DEBUG
  - setTransportModeLoggingOnly
```
public void setTransportModeLoggingOnly(boolean transportModeLoggingOnly)
```
    Sets the transport mode for this mail sender to logging only, which means no mail will be actually sent out.
    
    Parameters:
    
    transportModeLoggingOnly - Flag to indicate logging mode yes/no.
  - isTransportModeLoggingOnly
```
public boolean isTransportModeLoggingOnly()
```
    Returns:
    
    Whether this Mailer is set to only log or also actually send emails through an SMTP server (which is the default).
  - trustAllSSLHosts
```
public void trustAllSSLHosts(boolean trustAllHosts)
```
    Configures the current session to trust all hosts and don't validate any SSL keys. The property "mail.smtp.ssl.trust" is set to "*".
    Refer to https://javamail.java.net/nonav/docs/api/com/sun/mail/smtp/package-summary.html#mail.smtp.ssl.trust
  - trustSSLHosts
```
public void trustSSLHosts(String... hosts)
```
    Configures the current session to white list all provided hosts and don't validate SSL keys for them. The property "mail.smtp.ssl.trust" is set to a comma separated list.
    Refer to https://javamail.java.net/nonav/docs/api/com/sun/mail/smtp/package-summary.html#mail.smtp.ssl.trust
  - 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.
  - setThreadPoolSize
```
public void setThreadPoolSize(int poolSize)
```
    Parameters:
    
    poolSize - The maximum number of threads when sending emails in async fashion.
    
    See Also:
    
    ConfigLoader.Property.DEFAULT_POOL_SIZE
  - setSessionTimeout
```
public void setSessionTimeout(int sessionTimeout)
```
    Parameters:
    
    sessionTimeout - The timeout to use when sending emails (affects socket connect-, read- and write timeouts).
    
    See Also:
    
    ConfigLoader.Property.DEFAULT_SESSION_TIMEOUT_MILLIS
  - 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 message,
                                                                  Email email)
```
    Refer to MimeMessageHelper.signMessageWithDKIM(MimeMessage, Email)
  - setEmailAddressCriteria
```
public void setEmailAddressCriteria(EnumSet<org.hazlewood.connor.bottema.emailaddress.EmailAddressCriteria> emailAddressCriteria)
```
    Overrides the default email address validation restrictions emailAddressCriteria when validating and sending emails using the current Mailer instance.

Class Mailer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Mailer

Mailer

Mailer

Mailer

Mailer

Mailer

Mailer

Mailer

Mailer

Method Detail

createMailSession

getSession

setDebug

setTransportModeLoggingOnly

isTransportModeLoggingOnly

trustAllSSLHosts

trustSSLHosts

applyProperties

setThreadPoolSize

setSessionTimeout

sendMail

sendMail

validate

signMessageWithDKIM

setEmailAddressCriteria