org.apache.commons.mail
Class Email

java.lang.Object
  extended by 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
Version:
$Id: Email.java 1429384 2013-01-05 20:51:44Z tn $
Author:
Quinton McCombs, Jon S. Stevens, Frank Y. Kim, Brett McLaughlin, Greg Ritter, Regis Koenig, Colin Chalmers, Matthias Wessendorf, Corey Scott

Field Summary
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
Email()
           
 
Method Summary
 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.
 List<InternetAddress> getBccAddresses()
          Get the list of "Bcc" addresses.
 List<InternetAddress> getCcAddresses()
          Get the list of "CC" addresses.
 InternetAddress getFromAddress()
          Gets the sender of the 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 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 & 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.
 void setSentDate(Date date)
          Sets the sent date for the email.
 void setSmtpPort(int aPortNumber)
          Set the 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)
          Set 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 & 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
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.
Since:
1.3

setStartTLSRequired

public Email setStartTLSRequired(boolean startTlsRequired)
Set or disable the required STARTTLS encryption.

Parameters:
startTlsRequired - true if STARTTLS requested, false otherwise
Returns:
An Email.
Since:
1.3

setSmtpPort

public void setSmtpPort(int aPortNumber)
Set the port number of the outgoing mail server.

Parameters:
aPortNumber - aPortNumber
Since:
1.0

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
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 - JNDI name null or empty
NamingException - resource can 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 - thrown when 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.
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.
Since:
1.0

setSubject

public Email setSubject(String aSubject)
Set the email subject.

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

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.
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:
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:
EmailException - the sending failed

getMimeMessage

public MimeMessage getMimeMessage()
Returns the internal MimeMessage. Please not that the MimeMessage is build 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:
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).

Parameters:
ssl - whether to enable the SSL transport
Returns:
An Email.
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.
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

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


Copyright © 2001-2013 The Apache Software Foundation. All Rights Reserved.