org.apache.commons.mail

Class Email

java.lang.Object

org.apache.commons.mail.Email

Direct Known Subclasses:

MultiPartEmail, SimpleEmail

public abstract class Email
extends java.lang.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

Modifier and Type	Field and Description
static java.lang.String	ATTACHMENTS Deprecated. since 1.3, use EmailConstants.ATTACHMENTS instead
static java.lang.String	CONTENT_TYPE Deprecated. since 1.3, use EmailConstants.CONTENT_TYPE instead
static java.lang.String	EMAIL_BODY Deprecated. since 1.3, use EmailConstants.EMAIL_BODY instead
static java.lang.String	EMAIL_SUBJECT Deprecated. since 1.3, use EmailConstants.EMAIL_SUBJECT instead
static java.lang.String	FILE_SERVER Deprecated. since 1.3, use EmailConstants.FILE_SERVER instead
static java.lang.String	ISO_8859_1 Deprecated. since 1.3, use EmailConstants.ISO_8859_1 instead
static java.lang.String	KOI8_R Deprecated. since 1.3, use EmailConstants.KOI8_R instead
static java.lang.String	MAIL_DEBUG Deprecated. since 1.3, use EmailConstants.MAIL_DEBUG instead
static java.lang.String	MAIL_HOST Deprecated. since 1.3, use EmailConstants.MAIL_HOST instead
static java.lang.String	MAIL_PORT Deprecated. since 1.3, use EmailConstants.MAIL_PORT instead
static java.lang.String	MAIL_SMTP_AUTH Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_AUTH instead
static java.lang.String	MAIL_SMTP_CONNECTIONTIMEOUT Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_CONNECTIONTIMEOUT instead
static java.lang.String	MAIL_SMTP_FROM Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_FROM instead
static java.lang.String	MAIL_SMTP_PASSWORD Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_PASSWORD instead
static java.lang.String	MAIL_SMTP_SOCKET_FACTORY_CLASS Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_SOCKET_FACTORY_CLASS instead
static java.lang.String	MAIL_SMTP_SOCKET_FACTORY_FALLBACK Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_SOCKET_FACTORY_FALLBACK instead
static java.lang.String	MAIL_SMTP_SOCKET_FACTORY_PORT Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_SOCKET_FACTORY_PORT instead
static java.lang.String	MAIL_SMTP_TIMEOUT Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_TIMEOUT instead
static java.lang.String	MAIL_SMTP_USER Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_USER instead
static java.lang.String	MAIL_TRANSPORT_PROTOCOL Deprecated. since 1.3, use EmailConstants.MAIL_TRANSPORT_PROTOCOL instead
static java.lang.String	MAIL_TRANSPORT_TLS Deprecated. since 1.3, use EmailConstants.MAIL_TRANSPORT_TLS instead
static java.lang.String	RECEIVER_EMAIL Deprecated. since 1.3, use EmailConstants.RECEIVER_EMAIL instead
static java.lang.String	RECEIVER_NAME Deprecated. since 1.3, use EmailConstants.RECEIVER_NAME instead
static java.lang.String	SENDER_EMAIL Deprecated. since 1.3, use EmailConstants.SENDER_EMAIL instead
static java.lang.String	SENDER_NAME Deprecated. since 1.3, use EmailConstants.SENDER_NAME instead
static java.lang.String	SMTP Deprecated. since 1.3, use EmailConstants.SMTP instead
static java.lang.String	TEXT_HTML Deprecated. since 1.3, use EmailConstants.TEXT_HTML instead
static java.lang.String	TEXT_PLAIN Deprecated. since 1.3, use EmailConstants.TEXT_PLAIN instead
static java.lang.String	US_ASCII Deprecated. since 1.3, use EmailConstants.US_ASCII instead

Constructor Summary

Constructors

Constructor and Description
Email()

Method Summary

Modifier and Type	Method and Description
Email	addBcc(java.lang.String... emails) Add an array of blind BCC recipients to the email.
Email	addBcc(java.lang.String email) Add a blind BCC recipient to the email.
Email	addBcc(java.lang.String email, java.lang.String name) Add a blind BCC recipient to the email using the specified address and the specified personal name.
Email	addBcc(java.lang.String email, java.lang.String name, java.lang.String charset) Add a blind BCC recipient to the email using the specified address, personal name, and charset encoding for the name.
Email	addCc(java.lang.String... emails) Add an array of CC recipients to the email.
Email	addCc(java.lang.String email) Add a recipient CC to the email.
Email	addCc(java.lang.String email, java.lang.String name) Add a recipient CC to the email using the specified address and the specified personal name.
Email	addCc(java.lang.String email, java.lang.String name, java.lang.String charset) Add a recipient CC to the email using the specified address, personal name, and charset encoding for the name.
void	addHeader(java.lang.String name, java.lang.String value) Adds a header ( name, value ) to the headers Map.
Email	addReplyTo(java.lang.String email) Add a reply to address to the email.
Email	addReplyTo(java.lang.String email, java.lang.String name) Add a reply to address to the email using the specified address and the specified personal name.
Email	addReplyTo(java.lang.String email, java.lang.String name, java.lang.String charset) Add a reply to address to the email using the specified address, personal name, and charset encoding for the name.
Email	addTo(java.lang.String... emails) Add a list of TO recipients to the email.
Email	addTo(java.lang.String email) Add a recipient TO to the email.
Email	addTo(java.lang.String email, java.lang.String name) Add a recipient TO to the email using the specified address and the specified personal name.
Email	addTo(java.lang.String email, java.lang.String name, java.lang.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.
java.util.List<InternetAddress>	getBccAddresses() Get the list of "Bcc" addresses.
java.lang.String	getBounceAddress() Gets the "bounce address" of this email.
java.util.List<InternetAddress>	getCcAddresses() Get the list of "CC" addresses.
InternetAddress	getFromAddress() Gets the sender of the email.
java.lang.String	getHeader(java.lang.String header) Gets the specified header.
java.util.Map<java.lang.String,java.lang.String>	getHeaders() Gets all headers on an Email.
java.lang.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.
java.util.List<InternetAddress>	getReplyToAddresses() Get the list of "Reply-To" addresses.
java.util.Date	getSentDate() Gets the sent date for the email.
java.lang.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.
java.lang.String	getSslSmtpPort() Returns the current SSL port used by the SMTP transport.
java.lang.String	getSubject() Gets the subject of the email.
java.util.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
java.lang.String	send() Sends the email.
java.lang.String	sendMimeMessage() Sends the previously created MimeMessage to the SMTP server.
void	setAuthentication(java.lang.String userName, java.lang.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(java.util.Collection<InternetAddress> aCollection) Set a list of "BCC" addresses.
Email	setBounceAddress(java.lang.String email) Set the "bounce address" - the address to which undeliverable messages will be returned.
Email	setCc(java.util.Collection<InternetAddress> aCollection) Set a list of "CC" addresses.
void	setCharset(java.lang.String newCharset) Set the charset of the message.
void	setContent(MimeMultipart aMimeMultipart) Set the emailBody to a MimeMultiPart
void	setContent(java.lang.Object aObject, java.lang.String aContentType) Set the content and contentType.
void	setDebug(boolean d) Setting to true will enable the display of debug information.
Email	setFrom(java.lang.String email) Set the FROM field of the email to use the specified address.
Email	setFrom(java.lang.String email, java.lang.String name) Set the FROM field of the email to use the specified address and the specified personal name.
Email	setFrom(java.lang.String email, java.lang.String name, java.lang.String charset) Set the FROM field of the email to use the specified address, personal name, and charset encoding for the name.
void	setHeaders(java.util.Map<java.lang.String,java.lang.String> map) Used to specify the mail headers.
void	setHostName(java.lang.String aHostName) Set the hostname of the outgoing mail server.
void	setMailSession(Session aSession) Supply a mail Session object to use.
void	setMailSessionFromJNDI(java.lang.String jndiName) Supply a mail Session object from a JNDI directory.
abstract Email	setMsg(java.lang.String msg) Define the content of the mail.
void	setPopBeforeSmtp(boolean newPopBeforeSmtp, java.lang.String newPopHost, java.lang.String newPopUsername, java.lang.String newPopPassword) Set details regarding "pop3 before smtp" authentication.
Email	setReplyTo(java.util.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(java.util.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(java.lang.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(java.lang.String aSubject) Sets the email subject.
void	setTLS(boolean withTLS) Deprecated. since 1.3, use setStartTLSEnabled() instead
Email	setTo(java.util.Collection<InternetAddress> aCollection) Set a list of "TO" addresses.
void	updateContentType(java.lang.String aContentType) Update the contentType.

Methods inherited from class java.lang.Object

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

Field Detail

SENDER_EMAIL

@Deprecated
public static final java.lang.String SENDER_EMAIL

Deprecated. since 1.3, use EmailConstants.SENDER_EMAIL instead

See Also:

Constant Field Values

SENDER_NAME

@Deprecated
public static final java.lang.String SENDER_NAME

Deprecated. since 1.3, use EmailConstants.SENDER_NAME instead

See Also:

Constant Field Values

RECEIVER_EMAIL

@Deprecated
public static final java.lang.String RECEIVER_EMAIL

Deprecated. since 1.3, use EmailConstants.RECEIVER_EMAIL instead

See Also:

Constant Field Values

RECEIVER_NAME

@Deprecated
public static final java.lang.String RECEIVER_NAME

Deprecated. since 1.3, use EmailConstants.RECEIVER_NAME instead

See Also:

Constant Field Values

EMAIL_SUBJECT

@Deprecated
public static final java.lang.String EMAIL_SUBJECT

Deprecated. since 1.3, use EmailConstants.EMAIL_SUBJECT instead

See Also:

Constant Field Values

EMAIL_BODY

@Deprecated
public static final java.lang.String EMAIL_BODY

Deprecated. since 1.3, use EmailConstants.EMAIL_BODY instead

See Also:

Constant Field Values

CONTENT_TYPE

@Deprecated
public static final java.lang.String CONTENT_TYPE

Deprecated. since 1.3, use EmailConstants.CONTENT_TYPE instead

See Also:

Constant Field Values

ATTACHMENTS

@Deprecated
public static final java.lang.String ATTACHMENTS

Deprecated. since 1.3, use EmailConstants.ATTACHMENTS instead

See Also:

Constant Field Values

FILE_SERVER

@Deprecated
public static final java.lang.String FILE_SERVER

Deprecated. since 1.3, use EmailConstants.FILE_SERVER instead

See Also:

Constant Field Values

KOI8_R

@Deprecated
public static final java.lang.String KOI8_R

Deprecated. since 1.3, use EmailConstants.KOI8_R instead

See Also:

Constant Field Values

ISO_8859_1

@Deprecated
public static final java.lang.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 java.lang.String US_ASCII

Deprecated. since 1.3, use EmailConstants.US_ASCII instead

See Also:

Constant Field Values

MAIL_DEBUG

@Deprecated
public static final java.lang.String MAIL_DEBUG

Deprecated. since 1.3, use EmailConstants.MAIL_DEBUG instead

See Also:

Constant Field Values

MAIL_HOST

@Deprecated
public static final java.lang.String MAIL_HOST

Deprecated. since 1.3, use EmailConstants.MAIL_HOST instead

See Also:

Constant Field Values

MAIL_PORT

@Deprecated
public static final java.lang.String MAIL_PORT

Deprecated. since 1.3, use EmailConstants.MAIL_PORT instead

See Also:

Constant Field Values

MAIL_SMTP_FROM

@Deprecated
public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String MAIL_TRANSPORT_PROTOCOL

Deprecated. since 1.3, use EmailConstants.MAIL_TRANSPORT_PROTOCOL instead

See Also:

Constant Field Values

SMTP

@Deprecated
public static final java.lang.String SMTP

Deprecated. since 1.3, use EmailConstants.SMTP instead

See Also:

Constant Field Values

TEXT_HTML

@Deprecated
public static final java.lang.String TEXT_HTML

Deprecated. since 1.3, use EmailConstants.TEXT_HTML instead

See Also:

Constant Field Values

TEXT_PLAIN

@Deprecated
public static final java.lang.String TEXT_PLAIN

Deprecated. since 1.3, use EmailConstants.TEXT_PLAIN instead

See Also:

Constant Field Values

MAIL_TRANSPORT_TLS

@Deprecated
public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String MAIL_SMTP_TIMEOUT

Deprecated. since 1.3, use EmailConstants.MAIL_SMTP_TIMEOUT instead

See Also:

Constant Field Values

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(java.lang.String userName,
                              java.lang.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(java.lang.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:

java.nio.charset.IllegalCharsetNameException - if the charset name is invalid

java.nio.charset.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(java.lang.Object aObject,
                       java.lang.String aContentType)

Set the content and contentType.

Parameters:

aObject - aObject

aContentType - aContentType

Since:

1.0

updateContentType

public void updateContentType(java.lang.String aContentType)

Update the contentType.

Parameters:

aContentType - aContentType

Since:

1.2

setHostName

public void setHostName(java.lang.String aHostName)

Set the hostname of the outgoing mail server.

Parameters:

aHostName - aHostName

Throws:

java.lang.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:

java.lang.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:

java.lang.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:

java.lang.IllegalArgumentException - if the port number is < 1

java.lang.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:

java.lang.IllegalArgumentException - if the session is null

Since:

1.0

setMailSessionFromJNDI

public void setMailSessionFromJNDI(java.lang.String jndiName)
                            throws javax.naming.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:

java.lang.IllegalArgumentException - if the JNDI name is null or empty

javax.naming.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(java.lang.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(java.lang.String email,
                     java.lang.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(java.lang.String email,
                     java.lang.String name,
                     java.lang.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(java.lang.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(java.lang.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(java.lang.String email,
                   java.lang.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(java.lang.String email,
                   java.lang.String name,
                   java.lang.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(java.util.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(java.lang.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(java.lang.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(java.lang.String email,
                   java.lang.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(java.lang.String email,
                   java.lang.String name,
                   java.lang.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(java.util.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(java.lang.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(java.lang.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(java.lang.String email,
                    java.lang.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(java.lang.String email,
                    java.lang.String name,
                    java.lang.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(java.util.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(java.lang.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(java.lang.String email,
                        java.lang.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(java.lang.String email,
                        java.lang.String name,
                        java.lang.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(java.util.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(java.util.Map<java.lang.String,java.lang.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:

java.lang.IllegalArgumentException - if either of the provided header / value is null or empty

Since:

1.0

addHeader

public void addHeader(java.lang.String name,
                      java.lang.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:

java.lang.IllegalArgumentException - if either name or value is null or empty

Since:

1.0

getHeader

public java.lang.String getHeader(java.lang.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 java.util.Map<java.lang.String,java.lang.String> getHeaders()

Gets all headers on an Email.

Returns:

a Map of all headers.

Since:

1.5

setSubject

public Email setSubject(java.lang.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 java.lang.String getBounceAddress()

Gets the "bounce address" of this email.

Returns:

the bounce address as string

Since:

1.4

setBounceAddress

public Email setBounceAddress(java.lang.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:

java.lang.IllegalStateException - if the mail session is already initialized

Since:

1.0

setMsg

public abstract Email setMsg(java.lang.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:

java.lang.IllegalStateException - if the MimeMessage was already built

EmailException - if there was an error.

Since:

1.0

sendMimeMessage

public java.lang.String sendMimeMessage()
                                 throws EmailException

Sends the previously created MimeMessage to the SMTP server.

Returns:

the message id of the underlying MimeMessage

Throws:

java.lang.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 java.lang.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:

java.lang.IllegalStateException - if the MimeMessage was already built, ie buildMimeMessage() was already called

EmailException - the sending failed

setSentDate

public void setSentDate(java.util.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 java.util.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 java.lang.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 java.lang.String getHostName()

Gets the host name of the SMTP server,

Returns:

host name

getSmtpPort

public java.lang.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

setPopBeforeSmtp

public void setPopBeforeSmtp(boolean newPopBeforeSmtp,
                             java.lang.String newPopHost,
                             java.lang.String newPopUsername,
                             java.lang.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:

java.lang.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:

java.lang.IllegalStateException - if the mail session is already initialized

Since:

1.3

getSslSmtpPort

public java.lang.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(java.lang.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:

java.lang.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:

java.lang.IllegalStateException - if the mail session is already initialized

Since:

1.3.2

getToAddresses

public java.util.List<InternetAddress> getToAddresses()

Get the list of "To" addresses.

Returns:

List addresses

getCcAddresses

public java.util.List<InternetAddress> getCcAddresses()

Get the list of "CC" addresses.

Returns:

List addresses

getBccAddresses

public java.util.List<InternetAddress> getBccAddresses()

Get the list of "Bcc" addresses.

Returns:

List addresses

getReplyToAddresses

public java.util.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:

java.lang.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:

java.lang.IllegalStateException - if the mail session is already initialized

Since:

1.2