# Email (Apache Commons Email 1.5 API)

org.apache.commons.mail

## Class Email

- java.lang.Object
- - org.apache.commons.mail.Email

Direct Known Subclasses:
  MultiPartEmail, SimpleEmail

    public abstract class Email
    extends Object

The base class for all email messages. This class sets the sender's email & name, receiver's email & name, subject, and the sent date.

Subclasses are responsible for setting the message body.

Since:
  1.0

### Field Summary

Fields
`static String` `ATTACHMENTS` Deprecated. since 1.3, use `EmailConstants.ATTACHMENTS` instead
`protected Authenticator` `authenticator` Instance of an `Authenticator` object that will be used when authentication is requested from the mail server.
`protected List<InternetAddress>` `bccList` List of "bcc" email addresses.
`protected String` `bounceAddress` Address to which undeliverable mail should be sent.
`protected List<InternetAddress>` `ccList` List of "cc" email addresses.
`protected String` `charset` The charset to use for this message.
`protected Object` `content` The content.
`static String` `CONTENT_TYPE` Deprecated. since 1.3, use `EmailConstants.CONTENT_TYPE` instead
`protected String` `contentType` The content type.
`protected boolean` `debug` Set session debugging on or off.
`static String` `EMAIL_BODY` Deprecated. since 1.3, use `EmailConstants.EMAIL_BODY` instead
`static String` `EMAIL_SUBJECT` Deprecated. since 1.3, use `EmailConstants.EMAIL_SUBJECT` instead
`protected MimeMultipart` `emailBody` An attachment.
`static String` `FILE_SERVER` Deprecated. since 1.3, use `EmailConstants.FILE_SERVER` instead
`protected InternetAddress` `fromAddress` The Address of the sending party, mandatory.
`protected Map<String,String>` `headers` Used to specify the mail headers.
`protected String` `hostName` The hostname of the mail server with which to connect.
`static String` `ISO_8859_1` Deprecated. since 1.3, use `EmailConstants.ISO_8859_1` instead
`static String` `KOI8_R` Deprecated. since 1.3, use `EmailConstants.KOI8_R` instead
`static String` `MAIL_DEBUG` Deprecated. since 1.3, use `EmailConstants.MAIL_DEBUG` instead
`static String` `MAIL_HOST` Deprecated. since 1.3, use `EmailConstants.MAIL_HOST` instead
`static String` `MAIL_PORT` Deprecated. since 1.3, use `EmailConstants.MAIL_PORT` instead
`static String` `MAIL_SMTP_AUTH` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_AUTH` instead
`static String` `MAIL_SMTP_CONNECTIONTIMEOUT` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_CONNECTIONTIMEOUT` instead
`static String` `MAIL_SMTP_FROM` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_FROM` instead
`static String` `MAIL_SMTP_PASSWORD` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_PASSWORD` instead
`static String` `MAIL_SMTP_SOCKET_FACTORY_CLASS` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_CLASS` instead
`static String` `MAIL_SMTP_SOCKET_FACTORY_FALLBACK` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_FALLBACK` instead
`static String` `MAIL_SMTP_SOCKET_FACTORY_PORT` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_PORT` instead
`static String` `MAIL_SMTP_TIMEOUT` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_TIMEOUT` instead
`static String` `MAIL_SMTP_USER` Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_USER` instead
`static String` `MAIL_TRANSPORT_PROTOCOL` Deprecated. since 1.3, use `EmailConstants.MAIL_TRANSPORT_PROTOCOL` instead
`static String` `MAIL_TRANSPORT_TLS` Deprecated. since 1.3, use `EmailConstants.MAIL_TRANSPORT_TLS` instead
`protected MimeMessage` `message` The email message to send.
`protected boolean` `popBeforeSmtp` Used to determine whether to use pop3 before smtp, and if so the settings.
`protected String` `popHost` the host name of the pop3 server.
`protected String` `popPassword` the password to log into the pop3 server.
`protected String` `popUsername` the user name to log into the pop3 server.
`static String` `RECEIVER_EMAIL` Deprecated. since 1.3, use `EmailConstants.RECEIVER_EMAIL` instead
`static String` `RECEIVER_NAME` Deprecated. since 1.3, use `EmailConstants.RECEIVER_NAME` instead
`protected List<InternetAddress>` `replyList` List of "replyTo" email addresses.
`static String` `SENDER_EMAIL` Deprecated. since 1.3, use `EmailConstants.SENDER_EMAIL` instead
`static String` `SENDER_NAME` Deprecated. since 1.3, use `EmailConstants.SENDER_NAME` instead
`protected Date` `sentDate` Sent date.
`static String` `SMTP` Deprecated. since 1.3, use `EmailConstants.SMTP` instead
`protected String` `smtpPort` The port number of the mail server to connect to.
`protected int` `socketConnectionTimeout` socket connection timeout value in milliseconds.
`protected int` `socketTimeout` socket I/O timeout value in milliseconds.
`protected boolean` `ssl` Deprecated. since 1.3, use setSSLOnConnect() instead
`protected String` `sslSmtpPort` The port number of the SSL enabled SMTP server; defaults to the standard port, 465.
`protected String` `subject` The Subject.
`static String` `TEXT_HTML` Deprecated. since 1.3, use `EmailConstants.TEXT_HTML` instead
`static String` `TEXT_PLAIN` Deprecated. since 1.3, use `EmailConstants.TEXT_PLAIN` instead
`protected boolean` `tls` Deprecated. since 1.3, use setStartTLSEnabled() instead
`protected List<InternetAddress>` `toList` List of "to" email addresses.
`static String` `US_ASCII` Deprecated. since 1.3, use `EmailConstants.US_ASCII` instead

### Constructor Summary

Constructors
Constructor and Description
`Email()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`Email` `addBcc(String... emails)` Add an array of blind BCC recipients to the email.
`Email` `addBcc(String email)` Add a blind BCC recipient to the email.
`Email` `addBcc(String email, String name)` Add a blind BCC recipient to the email using the specified address and the specified personal name.
`Email` `addBcc(String email, String name, String charset)` Add a blind BCC recipient to the email using the specified address, personal name, and charset encoding for the name.
`Email` `addCc(String... emails)` Add an array of CC recipients to the email.
`Email` `addCc(String email)` Add a recipient CC to the email.
`Email` `addCc(String email, String name)` Add a recipient CC to the email using the specified address and the specified personal name.
`Email` `addCc(String email, String name, String charset)` Add a recipient CC to the email using the specified address, personal name, and charset encoding for the name.
`void` `addHeader(String name, String value)` Adds a header ( name, value ) to the headers Map.
`Email` `addReplyTo(String email)` Add a reply to address to the email.
`Email` `addReplyTo(String email, String name)` Add a reply to address to the email using the specified address and the specified personal name.
`Email` `addReplyTo(String email, String name, String charset)` Add a reply to address to the email using the specified address, personal name, and charset encoding for the name.
`Email` `addTo(String... emails)` Add a list of TO recipients to the email.
`Email` `addTo(String email)` Add a recipient TO to the email.
`Email` `addTo(String email, String name)` Add a recipient TO to the email using the specified address and the specified personal name.
`Email` `addTo(String email, String name, String charset)` Add a recipient TO to the email using the specified address, personal name, and charset encoding for the name.
`void` `buildMimeMessage()` Does the work of actually building the MimeMessage.
`protected MimeMessage` `createMimeMessage(Session aSession)` Factory method to create a customized MimeMessage which can be implemented by a derived class, e.g. to set the message id.
`List<InternetAddress>` `getBccAddresses()` Get the list of "Bcc" addresses.
`String` `getBounceAddress()` Gets the "bounce address" of this email.
`List<InternetAddress>` `getCcAddresses()` Get the list of "CC" addresses.
`InternetAddress` `getFromAddress()` Gets the sender of the email.
`String` `getHeader(String header)` Gets the specified header.
`Map<String,String>` `getHeaders()` Gets all headers on an Email.
`String` `getHostName()` Gets the host name of the SMTP server,
`Session` `getMailSession()` Determines the mail session used when sending this Email, creating the Session if necessary.
`MimeMessage` `getMimeMessage()` Returns the internal MimeMessage.
`List<InternetAddress>` `getReplyToAddresses()` Get the list of "Reply-To" addresses.
`Date` `getSentDate()` Gets the sent date for the email.
`String` `getSmtpPort()` Gets the listening port of the SMTP server.
`int` `getSocketConnectionTimeout()` Get the socket connection timeout value in milliseconds.
`int` `getSocketTimeout()` Get the socket I/O timeout value in milliseconds.
`String` `getSslSmtpPort()` Returns the current SSL port used by the SMTP transport.
`String` `getSubject()` Gets the subject of the email.
`List<InternetAddress>` `getToAddresses()` Get the list of "To" addresses.
`boolean` `isSendPartial()` If partial sending of email enabled.
`boolean` `isSSL()` Deprecated. since 1.3, use isSSLOnConnect() instead
`boolean` `isSSLCheckServerIdentity()` Is the server identity checked as specified by RFC 2595
`boolean` `isSSLOnConnect()` Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).
`boolean` `isStartTLSEnabled()` Gets whether the client is configured to try to enable STARTTLS.
`boolean` `isStartTLSRequired()` Gets whether the client is configured to require STARTTLS.
`boolean` `isTLS()` Deprecated. since 1.3, use isStartTLSEnabled() instead
`String` `send()` Sends the email.
`String` `sendMimeMessage()` Sends the previously created MimeMessage to the SMTP server.
`void` `setAuthentication(String userName, String password)` Sets the userName and password if authentication is needed.
`void` `setAuthenticator(Authenticator newAuthenticator)` Sets the `Authenticator` to be used when authentication is requested from the mail server.
`Email` `setBcc(Collection<InternetAddress> aCollection)` Set a list of "BCC" addresses.
`Email` `setBounceAddress(String email)` Set the "bounce address" - the address to which undeliverable messages will be returned.
`Email` `setCc(Collection<InternetAddress> aCollection)` Set a list of "CC" addresses.
`void` `setCharset(String newCharset)` Set the charset of the message.
`void` `setContent(MimeMultipart aMimeMultipart)` Set the emailBody to a MimeMultiPart
`void` `setContent(Object aObject, String aContentType)` Set the content and contentType.
`void` `setDebug(boolean d)` Setting to true will enable the display of debug information.
`Email` `setFrom(String email)` Set the FROM field of the email to use the specified address.
`Email` `setFrom(String email, String name)` Set the FROM field of the email to use the specified address and the specified personal name.
`Email` `setFrom(String email, String name, String charset)` Set the FROM field of the email to use the specified address, personal name, and charset encoding for the name.
`void` `setHeaders(Map<String,String> map)` Used to specify the mail headers.
`void` `setHostName(String aHostName)` Set the hostname of the outgoing mail server.
`void` `setMailSession(Session aSession)` Supply a mail Session object to use.
`void` `setMailSessionFromJNDI(String jndiName)` Supply a mail Session object from a JNDI directory.
`abstract Email` `setMsg(String msg)` Define the content of the mail.
`void` `setPopBeforeSmtp(boolean newPopBeforeSmtp, String newPopHost, String newPopUsername, String newPopPassword)` Set details regarding "pop3 before smtp" authentication.
`Email` `setReplyTo(Collection<InternetAddress> aCollection)` Set a list of reply to addresses.
`Email` `setSendPartial(boolean sendPartial)` Sets whether the email is partially send in case of invalid addresses.
`void` `setSentDate(Date date)` Sets the sent date for the email.
`void` `setSmtpPort(int aPortNumber)` Set the non-SSL port number of the outgoing mail server.
`void` `setSocketConnectionTimeout(int socketConnectionTimeout)` Set the socket connection timeout value in milliseconds.
`void` `setSocketTimeout(int socketTimeout)` Set the socket I/O timeout value in milliseconds.
`void` `setSSL(boolean ssl)` Deprecated. since 1.3, use setSSLOnConnect() instead
`Email` `setSSLCheckServerIdentity(boolean sslCheckServerIdentity)` Sets whether the server identity is checked as specified by RFC 2595
`Email` `setSSLOnConnect(boolean ssl)` Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS).
`void` `setSslSmtpPort(String sslSmtpPort)` Sets the SSL port to use for the SMTP transport.
`Email` `setStartTLSEnabled(boolean startTlsEnabled)` Set or disable the STARTTLS encryption.
`Email` `setStartTLSRequired(boolean startTlsRequired)` Set or disable the required STARTTLS encryption.
`Email` `setSubject(String aSubject)` Sets the email subject.
`void` `setTLS(boolean withTLS)` Deprecated. since 1.3, use setStartTLSEnabled() instead
`Email` `setTo(Collection<InternetAddress> aCollection)` Set a list of "TO" addresses.
`protected InternetAddress[]` `toInternetAddressArray(List<InternetAddress> list)` Utility to copy List of known InternetAddress objects into an array.
`void` `updateContentType(String aContentType)` Update the contentType.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### SENDER_EMAIL

    @Deprecated
    public static final String SENDER_EMAIL

Deprecated. since 1.3, use `EmailConstants.SENDER_EMAIL` instead

See Also:
  Constant Field Values

#### SENDER_NAME

    @Deprecated
    public static final String SENDER_NAME

Deprecated. since 1.3, use `EmailConstants.SENDER_NAME` instead

See Also:
  Constant Field Values

#### RECEIVER_EMAIL

    @Deprecated
    public static final String RECEIVER_EMAIL

Deprecated. since 1.3, use `EmailConstants.RECEIVER_EMAIL` instead

See Also:
  Constant Field Values

#### RECEIVER_NAME

    @Deprecated
    public static final String RECEIVER_NAME

Deprecated. since 1.3, use `EmailConstants.RECEIVER_NAME` instead

See Also:
  Constant Field Values

#### EMAIL_SUBJECT

    @Deprecated
    public static final String EMAIL_SUBJECT

Deprecated. since 1.3, use `EmailConstants.EMAIL_SUBJECT` instead

See Also:
  Constant Field Values

#### EMAIL_BODY

    @Deprecated
    public static final String EMAIL_BODY

Deprecated. since 1.3, use `EmailConstants.EMAIL_BODY` instead

See Also:
  Constant Field Values

#### CONTENT_TYPE

    @Deprecated
    public static final String CONTENT_TYPE

Deprecated. since 1.3, use `EmailConstants.CONTENT_TYPE` instead

See Also:
  Constant Field Values

#### ATTACHMENTS

    @Deprecated
    public static final String ATTACHMENTS

Deprecated. since 1.3, use `EmailConstants.ATTACHMENTS` instead

See Also:
  Constant Field Values

#### FILE_SERVER

    @Deprecated
    public static final String FILE_SERVER

Deprecated. since 1.3, use `EmailConstants.FILE_SERVER` instead

See Also:
  Constant Field Values

#### KOI8_R

    @Deprecated
    public static final String KOI8_R

Deprecated. since 1.3, use `EmailConstants.KOI8_R` instead

See Also:
  Constant Field Values

#### ISO_8859_1

    @Deprecated
    public static final String ISO_8859_1

Deprecated. since 1.3, use `EmailConstants.ISO_8859_1` instead

See Also:
  Constant Field Values

#### US_ASCII

    @Deprecated
    public static final String US_ASCII

Deprecated. since 1.3, use `EmailConstants.US_ASCII` instead

See Also:
  Constant Field Values

#### MAIL_DEBUG

    @Deprecated
    public static final String MAIL_DEBUG

Deprecated. since 1.3, use `EmailConstants.MAIL_DEBUG` instead

See Also:
  Constant Field Values

#### MAIL_HOST

    @Deprecated
    public static final String MAIL_HOST

Deprecated. since 1.3, use `EmailConstants.MAIL_HOST` instead

See Also:
  Constant Field Values

#### MAIL_PORT

    @Deprecated
    public static final String MAIL_PORT

Deprecated. since 1.3, use `EmailConstants.MAIL_PORT` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_FROM

    @Deprecated
    public static final String MAIL_SMTP_FROM

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_FROM` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_AUTH

    @Deprecated
    public static final String MAIL_SMTP_AUTH

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_AUTH` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_USER

    @Deprecated
    public static final String MAIL_SMTP_USER

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_USER` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_PASSWORD

    @Deprecated
    public static final String MAIL_SMTP_PASSWORD

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_PASSWORD` instead

See Also:
  Constant Field Values

#### MAIL_TRANSPORT_PROTOCOL

    @Deprecated
    public static final String MAIL_TRANSPORT_PROTOCOL

Deprecated. since 1.3, use `EmailConstants.MAIL_TRANSPORT_PROTOCOL` instead

See Also:
  Constant Field Values

#### SMTP

    @Deprecated
    public static final String SMTP

Deprecated. since 1.3, use `EmailConstants.SMTP` instead

See Also:
  Constant Field Values

#### TEXT_HTML

    @Deprecated
    public static final String TEXT_HTML

Deprecated. since 1.3, use `EmailConstants.TEXT_HTML` instead

See Also:
  Constant Field Values

#### TEXT_PLAIN

    @Deprecated
    public static final String TEXT_PLAIN

Deprecated. since 1.3, use `EmailConstants.TEXT_PLAIN` instead

See Also:
  Constant Field Values

#### MAIL_TRANSPORT_TLS

    @Deprecated
    public static final String MAIL_TRANSPORT_TLS

Deprecated. since 1.3, use `EmailConstants.MAIL_TRANSPORT_TLS` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_SOCKET_FACTORY_FALLBACK

    @Deprecated
    public static final String MAIL_SMTP_SOCKET_FACTORY_FALLBACK

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_FALLBACK` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_SOCKET_FACTORY_CLASS

    @Deprecated
    public static final String MAIL_SMTP_SOCKET_FACTORY_CLASS

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_CLASS` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_SOCKET_FACTORY_PORT

    @Deprecated
    public static final String MAIL_SMTP_SOCKET_FACTORY_PORT

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_SOCKET_FACTORY_PORT` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_CONNECTIONTIMEOUT

    @Deprecated
    public static final String MAIL_SMTP_CONNECTIONTIMEOUT

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_CONNECTIONTIMEOUT` instead

See Also:
  Constant Field Values

#### MAIL_SMTP_TIMEOUT

    @Deprecated
    public static final String MAIL_SMTP_TIMEOUT

Deprecated. since 1.3, use `EmailConstants.MAIL_SMTP_TIMEOUT` instead

See Also:
  Constant Field Values

#### message

    protected MimeMessage message

The email message to send.

#### charset

    protected String charset

The charset to use for this message.

#### fromAddress

    protected InternetAddress fromAddress

The Address of the sending party, mandatory.

#### subject

    protected String subject

The Subject.

#### emailBody

    protected MimeMultipart emailBody

An attachment.

#### content

    protected Object content

The content.

#### contentType

    protected String contentType

The content type.

#### debug

    protected boolean debug

Set session debugging on or off.

#### sentDate

    protected Date sentDate

Sent date.

#### authenticator

    protected Authenticator authenticator

Instance of an `Authenticator` object that will be used when authentication is requested from the mail server.

#### hostName

    protected String hostName

The hostname of the mail server with which to connect. If null will try to get property from system.properties. If still null, quit.

#### smtpPort

    protected String smtpPort

The port number of the mail server to connect to. Defaults to the standard port ( 25 ).

#### sslSmtpPort

    protected String sslSmtpPort

The port number of the SSL enabled SMTP server; defaults to the standard port, 465.

#### toList

    protected List<InternetAddress> toList

List of "to" email addresses.

#### ccList

    protected List<InternetAddress> ccList

List of "cc" email addresses.

#### bccList

    protected List<InternetAddress> bccList

List of "bcc" email addresses.

#### replyList

    protected List<InternetAddress> replyList

List of "replyTo" email addresses.

#### bounceAddress

    protected String bounceAddress

Address to which undeliverable mail should be sent. Because this is handled by JavaMail as a String property in the mail session, this property is of type `String` rather than `InternetAddress`.

#### headers

    protected Map<String,String> headers

Used to specify the mail headers. Example: X-Mailer: Sendmail, X-Priority: 1( highest ) or 2( high ) 3( normal ) 4( low ) and 5( lowest ) Disposition-Notification-To: user@domain.net

#### popBeforeSmtp

    protected boolean popBeforeSmtp

Used to determine whether to use pop3 before smtp, and if so the settings.

#### popHost

    protected String popHost

the host name of the pop3 server.

#### popUsername

    protected String popUsername

the user name to log into the pop3 server.

#### popPassword

    protected String popPassword

the password to log into the pop3 server.

#### tls

    @Deprecated
    protected boolean tls

Deprecated. since 1.3, use setStartTLSEnabled() instead
Does server require TLS encryption for authentication?

#### ssl

    @Deprecated
    protected boolean ssl

Deprecated. since 1.3, use setSSLOnConnect() instead
Does the current transport use SSL/TLS encryption upon connection?

#### socketTimeout

    protected int socketTimeout

socket I/O timeout value in milliseconds.

#### socketConnectionTimeout

    protected int socketConnectionTimeout

socket connection timeout value in milliseconds.

### Constructor Detail

#### Email

    public Email()

### Method Detail

#### setDebug

    public void setDebug(boolean d)

Setting to true will enable the display of debug information.

Parameters:
  `d` - A boolean.
Since:
  1.0

#### setAuthentication

    public void setAuthentication(String userName,
                                  String password)

Sets the userName and password if authentication is needed. If this method is not used, no authentication will be performed.

This method will create a new instance of `DefaultAuthenticator` using the supplied parameters.

Parameters:
  `userName` - User name for the SMTP server
  `password` - password for the SMTP server
Since:
  1.0
See Also:
  `DefaultAuthenticator`, `setAuthenticator(javax.mail.Authenticator)`

#### setAuthenticator

    public void setAuthenticator(Authenticator newAuthenticator)

Sets the `Authenticator` to be used when authentication is requested from the mail server.

This method should be used when your outgoing mail server requires authentication. Your mail server must also support RFC2554.

Parameters:
  `newAuthenticator` - the `Authenticator` object.
Since:
  1.0
See Also:
  `Authenticator`

#### setCharset

    public void setCharset(String newCharset)

Set the charset of the message. Please note that you should set the charset before adding the message content.

Parameters:
  `newCharset` - A String.
Throws:
  `IllegalCharsetNameException` - if the charset name is invalid
  `UnsupportedCharsetException` - if no support for the named charset exists in the current JVM
Since:
  1.0

#### setContent

    public void setContent(MimeMultipart aMimeMultipart)

Set the emailBody to a MimeMultiPart

Parameters:
  `aMimeMultipart` - aMimeMultipart
Since:
  1.0

#### setContent

    public void setContent(Object aObject,
                           String aContentType)

Set the content and contentType.

Parameters:
  `aObject` - aObject
  `aContentType` - aContentType
Since:
  1.0

#### updateContentType

    public void updateContentType(String aContentType)

Update the contentType.

Parameters:
  `aContentType` - aContentType
Since:
  1.2

#### setHostName

    public void setHostName(String aHostName)

Set the hostname of the outgoing mail server.

Parameters:
  `aHostName` - aHostName
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.0

#### setTLS

    @Deprecated
    public void setTLS(boolean withTLS)

Deprecated. since 1.3, use setStartTLSEnabled() instead
Set or disable the STARTTLS encryption. Please see EMAIL-105 for the reasons of deprecation.

Parameters:
  `withTLS` - true if STARTTLS requested, false otherwise
Since:
  1.1

#### setStartTLSEnabled

    public Email setStartTLSEnabled(boolean startTlsEnabled)

Set or disable the STARTTLS encryption.

Parameters:
  `startTlsEnabled` - true if STARTTLS requested, false otherwise
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.3

#### setStartTLSRequired

    public Email setStartTLSRequired(boolean startTlsRequired)

Set or disable the required STARTTLS encryption.

Defaults to `smtpPort`; can be overridden by using `setSmtpPort(int)`

Parameters:
  `startTlsRequired` - true if STARTTLS requested, false otherwise
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.3

#### setSmtpPort

    public void setSmtpPort(int aPortNumber)

Set the non-SSL port number of the outgoing mail server.

Parameters:
  `aPortNumber` - aPortNumber
Throws:
  `IllegalArgumentException` - if the port number is < 1
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.0
See Also:
  `setSslSmtpPort(String)`

#### setMailSession

    public void setMailSession(Session aSession)

Supply a mail Session object to use. Please note that passing a user name and password (in the case of mail authentication) will create a new mail session with a DefaultAuthenticator. This is a convenience but might come unexpected. If mail authentication is used but NO username and password is supplied the implementation assumes that you have set a authenticator and will use the existing mail session (as expected).

Parameters:
  `aSession` - mail session to be used
Throws:
  `IllegalArgumentException` - if the session is `null`
Since:
  1.0

#### setMailSessionFromJNDI

    public void setMailSessionFromJNDI(String jndiName)
                                throws NamingException

Supply a mail Session object from a JNDI directory.

Parameters:
  `jndiName` - name of JNDI resource (javax.mail.Session type), resource if searched in java:comp/env if name does not start with "java:"
Throws:
  `IllegalArgumentException` - if the JNDI name is null or empty
  `NamingException` - if the resource cannot be retrieved from JNDI directory
Since:
  1.1

#### getMailSession

    public Session getMailSession()
                           throws EmailException

Determines the mail session used when sending this Email, creating the Session if necessary. When a mail session is already initialized setting the session related properties will cause an IllegalStateException.

Returns:
  A Session.
Throws:
  `EmailException` - if the host name was not set
Since:
  1.0

#### setFrom

    public Email setFrom(String email)
                  throws EmailException

Set the FROM field of the email to use the specified address. The email address will also be used as the personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### setFrom

    public Email setFrom(String email,
                         String name)
                  throws EmailException

Set the FROM field of the email to use the specified address and the specified personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
  `name` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### setFrom

    public Email setFrom(String email,
                         String name,
                         String charset)
                  throws EmailException

Set the FROM field of the email to use the specified address, personal name, and charset encoding for the name.

Parameters:
  `email` - A String.
  `name` - A String.
  `charset` - The charset to encode the name with.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address or charset.
Since:
  1.1

#### addTo

    public Email addTo(String email)
                throws EmailException

Add a recipient TO to the email. The email address will also be used as the personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### addTo

    public Email addTo(String... emails)
                throws EmailException

Add a list of TO recipients to the email. The email addresses will also be used as the personal names. The names will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `emails` - A String array.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.3

#### addTo

    public Email addTo(String email,
                       String name)
                throws EmailException

Add a recipient TO to the email using the specified address and the specified personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
  `name` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### addTo

    public Email addTo(String email,
                       String name,
                       String charset)
                throws EmailException

Add a recipient TO to the email using the specified address, personal name, and charset encoding for the name.

Parameters:
  `email` - A String.
  `name` - A String.
  `charset` - The charset to encode the name with.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address or charset.
Since:
  1.1

#### setTo

    public Email setTo(Collection<InternetAddress> aCollection)
                throws EmailException

Set a list of "TO" addresses. All elements in the specified `Collection` are expected to be of type `java.mail.internet.InternetAddress`.

Parameters:
  `aCollection` - collection of `InternetAddress` objects.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0
See Also:
  `InternetAddress`

#### addCc

    public Email addCc(String email)
                throws EmailException

Add a recipient CC to the email. The email address will also be used as the personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### addCc

    public Email addCc(String... emails)
                throws EmailException

Add an array of CC recipients to the email. The email addresses will also be used as the personal name. The names will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `emails` - A String array.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.3

#### addCc

    public Email addCc(String email,
                       String name)
                throws EmailException

Add a recipient CC to the email using the specified address and the specified personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
  `name` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0

#### addCc

    public Email addCc(String email,
                       String name,
                       String charset)
                throws EmailException

Add a recipient CC to the email using the specified address, personal name, and charset encoding for the name.

Parameters:
  `email` - A String.
  `name` - A String.
  `charset` - The charset to encode the name with.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address or charset.
Since:
  1.1

#### setCc

    public Email setCc(Collection<InternetAddress> aCollection)
                throws EmailException

Set a list of "CC" addresses. All elements in the specified `Collection` are expected to be of type `java.mail.internet.InternetAddress`.

Parameters:
  `aCollection` - collection of `InternetAddress` objects.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address.
Since:
  1.0
See Also:
  `InternetAddress`

#### addBcc

    public Email addBcc(String email)
                 throws EmailException

Add a blind BCC recipient to the email. The email address will also be used as the personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.0

#### addBcc

    public Email addBcc(String... emails)
                 throws EmailException

Add an array of blind BCC recipients to the email. The email addresses will also be used as the personal name. The names will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `emails` - A String array.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.3

#### addBcc

    public Email addBcc(String email,
                        String name)
                 throws EmailException

Add a blind BCC recipient to the email using the specified address and the specified personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
  `name` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.0

#### addBcc

    public Email addBcc(String email,
                        String name,
                        String charset)
                 throws EmailException

Add a blind BCC recipient to the email using the specified address, personal name, and charset encoding for the name.

Parameters:
  `email` - A String.
  `name` - A String.
  `charset` - The charset to encode the name with.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.1

#### setBcc

    public Email setBcc(Collection<InternetAddress> aCollection)
                 throws EmailException

Set a list of "BCC" addresses. All elements in the specified `Collection` are expected to be of type `java.mail.internet.InternetAddress`.

Parameters:
  `aCollection` - collection of `InternetAddress` objects
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.0
See Also:
  `InternetAddress`

#### addReplyTo

    public Email addReplyTo(String email)
                     throws EmailException

Add a reply to address to the email. The email address will also be used as the personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.0

#### addReplyTo

    public Email addReplyTo(String email,
                            String name)
                     throws EmailException

Add a reply to address to the email using the specified address and the specified personal name. The name will be encoded by the charset of `setCharset()`. If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.

Parameters:
  `email` - A String.
  `name` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.0

#### addReplyTo

    public Email addReplyTo(String email,
                            String name,
                            String charset)
                     throws EmailException

Add a reply to address to the email using the specified address, personal name, and charset encoding for the name.

Parameters:
  `email` - A String.
  `name` - A String.
  `charset` - The charset to encode the name with.
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address or charset.
Since:
  1.1

#### setReplyTo

    public Email setReplyTo(Collection<InternetAddress> aCollection)
                     throws EmailException

Set a list of reply to addresses. All elements in the specified `Collection` are expected to be of type `java.mail.internet.InternetAddress`.

Parameters:
  `aCollection` - collection of `InternetAddress` objects
Returns:
  An Email.
Throws:
  `EmailException` - Indicates an invalid email address
Since:
  1.1
See Also:
  `InternetAddress`

#### setHeaders

    public void setHeaders(Map<String,String> map)

Used to specify the mail headers. Example: X-Mailer: Sendmail, X-Priority: 1( highest ) or 2( high ) 3( normal ) 4( low ) and 5( lowest ) Disposition-Notification-To: user@domain.net

Parameters:
  `map` - A Map.
Throws:
  `IllegalArgumentException` - if either of the provided header / value is null or empty
Since:
  1.0

#### addHeader

    public void addHeader(String name,
                          String value)

Adds a header ( name, value ) to the headers Map.

Parameters:
  `name` - A String with the name.
  `value` - A String with the value.
Throws:
  `IllegalArgumentException` - if either `name` or `value` is null or empty
Since:
  1.0

#### getHeader

    public String getHeader(String header)

Gets the specified header.

Parameters:
  `header` - A string with the header.
Returns:
  The value of the header, or null if no such header.
Since:
  1.5

#### getHeaders

    public Map<String,String> getHeaders()

Gets all headers on an Email.

Returns:
  a Map of all headers.
Since:
  1.5

#### setSubject

    public Email setSubject(String aSubject)

Sets the email subject. Replaces end-of-line characters with spaces.

Parameters:
  `aSubject` - A String.
Returns:
  An Email.
Since:
  1.0

#### getBounceAddress

    public String getBounceAddress()

Gets the "bounce address" of this email.

Returns:
  the bounce address as string
Since:
  1.4

#### setBounceAddress

    public Email setBounceAddress(String email)

Set the "bounce address" - the address to which undeliverable messages will be returned. If this value is never set, then the message will be sent to the address specified with the System property "mail.smtp.from", or if that value is not set, then to the "from" address.

Parameters:
  `email` - A String.
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.0

#### setMsg

    public abstract Email setMsg(String msg)
                          throws EmailException

Define the content of the mail. It should be overridden by the subclasses.

Parameters:
  `msg` - A String.
Returns:
  An Email.
Throws:
  `EmailException` - generic exception.
Since:
  1.0

#### buildMimeMessage

    public void buildMimeMessage()
                          throws EmailException

Does the work of actually building the MimeMessage. Please note that a user rarely calls this method directly and only if he/she is interested in the sending the underlying MimeMessage without commons-email.

Throws:
  `IllegalStateException` - if the MimeMessage was already built
  `EmailException` - if there was an error.
Since:
  1.0

#### sendMimeMessage

    public String sendMimeMessage()
                           throws EmailException

Sends the previously created MimeMessage to the SMTP server.

Returns:
  the message id of the underlying MimeMessage
Throws:
  `IllegalArgumentException` - if the MimeMessage has not been created
  `EmailException` - the sending failed

#### getMimeMessage

    public MimeMessage getMimeMessage()

Returns the internal MimeMessage. Please note that the MimeMessage is built by the buildMimeMessage() method.

Returns:
  the MimeMessage

#### send

    public String send()
                throws EmailException

Sends the email. Internally we build a MimeMessage which is afterwards sent to the SMTP server.

Returns:
  the message id of the underlying MimeMessage
Throws:
  `IllegalStateException` - if the MimeMessage was already built, ie `buildMimeMessage()` was already called
  `EmailException` - the sending failed

#### setSentDate

    public void setSentDate(Date date)

Sets the sent date for the email. The sent date will default to the current date if not explicitly set.

Parameters:
  `date` - Date to use as the sent date on the email
Since:
  1.0

#### getSentDate

    public Date getSentDate()

Gets the sent date for the email.

Returns:
  date to be used as the sent date for the email
Since:
  1.0

#### getSubject

    public String getSubject()

Gets the subject of the email.

Returns:
  email subject

#### getFromAddress

    public InternetAddress getFromAddress()

Gets the sender of the email.

Returns:
  from address

#### getHostName

    public String getHostName()

Gets the host name of the SMTP server,

Returns:
  host name

#### getSmtpPort

    public String getSmtpPort()

Gets the listening port of the SMTP server.

Returns:
  smtp port

#### isStartTLSRequired

    public boolean isStartTLSRequired()

Gets whether the client is configured to require STARTTLS.

Returns:
  true if using STARTTLS for authentication, false otherwise
Since:
  1.3

#### isStartTLSEnabled

    public boolean isStartTLSEnabled()

Gets whether the client is configured to try to enable STARTTLS.

Returns:
  true if using STARTTLS for authentication, false otherwise
Since:
  1.3

#### isTLS

    @Deprecated
    public boolean isTLS()

Deprecated. since 1.3, use isStartTLSEnabled() instead
Gets whether the client is configured to try to enable STARTTLS. See EMAIL-105 for reason of deprecation.

Returns:
  true if using STARTTLS for authentication, false otherwise
Since:
  1.1

#### toInternetAddressArray

    protected InternetAddress[] toInternetAddressArray(List<InternetAddress> list)

Utility to copy List of known InternetAddress objects into an array.

Parameters:
  `list` - A List.
Returns:
  An InternetAddress[].
Since:
  1.0

#### setPopBeforeSmtp

    public void setPopBeforeSmtp(boolean newPopBeforeSmtp,
                                 String newPopHost,
                                 String newPopUsername,
                                 String newPopPassword)

Set details regarding "pop3 before smtp" authentication.

Parameters:
  `newPopBeforeSmtp` - Whether or not to log into pop3 server before sending mail.
  `newPopHost` - The pop3 host to use.
  `newPopUsername` - The pop3 username.
  `newPopPassword` - The pop3 password.
Since:
  1.0

#### isSSL

    @Deprecated
    public boolean isSSL()

Deprecated. since 1.3, use isSSLOnConnect() instead
Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS). See EMAIL-105 for reason of deprecation.

Returns:
  true if SSL enabled for the transport

#### isSSLOnConnect

    public boolean isSSLOnConnect()

Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).

Returns:
  true if SSL enabled for the transport
Since:
  1.3

#### setSSL

    @Deprecated
    public void setSSL(boolean ssl)

Deprecated. since 1.3, use setSSLOnConnect() instead
Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS). See EMAIL-105 for reason of deprecation.

Parameters:
  `ssl` - whether to enable the SSL transport

#### setSSLOnConnect

    public Email setSSLOnConnect(boolean ssl)

Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS). Takes precedence over `setStartTLSRequired(boolean)`

Defaults to `sslSmtpPort`; can be overridden by using `setSslSmtpPort(String)`

Parameters:
  `ssl` - whether to enable the SSL transport
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.3

#### isSSLCheckServerIdentity

    public boolean isSSLCheckServerIdentity()

Is the server identity checked as specified by RFC 2595

Returns:
  true if the server identity is checked
Since:
  1.3

#### setSSLCheckServerIdentity

    public Email setSSLCheckServerIdentity(boolean sslCheckServerIdentity)

Sets whether the server identity is checked as specified by RFC 2595

Parameters:
  `sslCheckServerIdentity` - whether to enable server identity check
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.3

#### getSslSmtpPort

    public String getSslSmtpPort()

Returns the current SSL port used by the SMTP transport.

Returns:
  the current SSL port used by the SMTP transport

#### setSslSmtpPort

    public void setSslSmtpPort(String sslSmtpPort)

Sets the SSL port to use for the SMTP transport. Defaults to the standard port, 465.

Parameters:
  `sslSmtpPort` - the SSL port to use for the SMTP transport
Throws:
  `IllegalStateException` - if the mail session is already initialized
See Also:
  `setSmtpPort(int)`

#### isSendPartial

    public boolean isSendPartial()

If partial sending of email enabled.

Returns:
  true if sending partial email is enabled
Since:
  1.3.2

#### setSendPartial

    public Email setSendPartial(boolean sendPartial)

Sets whether the email is partially send in case of invalid addresses.

In case the mail server rejects an address as invalid, the call to `send()` may throw a `SendFailedException`, even if partial send mode is enabled (emails to valid addresses will be transmitted). In case the email server does not reject invalid addresses immediately, but return a bounce message, no exception will be thrown by the `send()` method.

Parameters:
  `sendPartial` - whether to enable partial send mode
Returns:
  An Email.
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.3.2

#### getToAddresses

    public List<InternetAddress> getToAddresses()

Get the list of "To" addresses.

Returns:
  List addresses

#### getCcAddresses

    public List<InternetAddress> getCcAddresses()

Get the list of "CC" addresses.

Returns:
  List addresses

#### getBccAddresses

    public List<InternetAddress> getBccAddresses()

Get the list of "Bcc" addresses.

Returns:
  List addresses

#### getReplyToAddresses

    public List<InternetAddress> getReplyToAddresses()

Get the list of "Reply-To" addresses.

Returns:
  List addresses

#### getSocketConnectionTimeout

    public int getSocketConnectionTimeout()

Get the socket connection timeout value in milliseconds.

Returns:
  the timeout in milliseconds.
Since:
  1.2

#### setSocketConnectionTimeout

    public void setSocketConnectionTimeout(int socketConnectionTimeout)

Set the socket connection timeout value in milliseconds. Default is a 60 second timeout.

Parameters:
  `socketConnectionTimeout` - the connection timeout
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.2

#### getSocketTimeout

    public int getSocketTimeout()

Get the socket I/O timeout value in milliseconds.

Returns:
  the socket I/O timeout
Since:
  1.2

#### setSocketTimeout

    public void setSocketTimeout(int socketTimeout)

Set the socket I/O timeout value in milliseconds. Default is 60 second timeout.

Parameters:
  `socketTimeout` - the socket I/O timeout
Throws:
  `IllegalStateException` - if the mail session is already initialized
Since:
  1.2

#### createMimeMessage

    protected MimeMessage createMimeMessage(Session aSession)

Factory method to create a customized MimeMessage which can be implemented by a derived class, e.g. to set the message id.

Parameters:
  `aSession` - mail session to be used
Returns:
  the newly created message