Class Email
- Direct Known Subclasses:
MultiPartEmail
,SimpleEmail
Subclasses are responsible for setting the message body.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Deprecated.protected javax.mail.Authenticator
Instance of anAuthenticator
object that will be used when authentication is requested from the mail server.protected List<javax.mail.internet.InternetAddress>
List of "bcc" email addresses.protected String
Address to which undeliverable mail should be sent.protected List<javax.mail.internet.InternetAddress>
List of "cc" email addresses.protected String
The charset to use for this message.protected Object
The content.static final String
Deprecated.since 1.3, useEmailConstants.CONTENT_TYPE
insteadprotected String
The content type.protected boolean
Set session debugging on or off.static final String
Deprecated.since 1.3, useEmailConstants.EMAIL_BODY
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.EMAIL_SUBJECT
insteadprotected javax.mail.internet.MimeMultipart
An attachment.static final String
Deprecated.since 1.3, useEmailConstants.FILE_SERVER
insteadprotected javax.mail.internet.InternetAddress
The Address of the sending party, mandatory.Used to specify the mail headers.protected String
The hostname of the mail server with which to connect.static final String
Deprecated.since 1.3, useEmailConstants.ISO_8859_1
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.KOI8_R
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_DEBUG
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_HOST
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_PORT
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_AUTH
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_CONNECTIONTIMEOUT
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_FROM
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_PASSWORD
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_CLASS
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_FALLBACK
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_PORT
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_TIMEOUT
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_USER
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_TRANSPORT_PROTOCOL
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.MAIL_TRANSPORT_TLS
insteadprotected javax.mail.internet.MimeMessage
The email message to send.protected boolean
Used to determine whether to use pop3 before smtp, and if so the settings.protected String
the host name of the pop3 server.protected String
the password to log into the pop3 server.protected String
the user name to log into the pop3 server.static final String
Deprecated.since 1.3, useEmailConstants.RECEIVER_EMAIL
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.RECEIVER_NAME
insteadprotected List<javax.mail.internet.InternetAddress>
List of "replyTo" email addresses.static final String
Deprecated.since 1.3, useEmailConstants.SENDER_EMAIL
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.SENDER_NAME
insteadprotected Date
Sent date.static final String
Deprecated.since 1.3, useEmailConstants.SMTP
insteadprotected String
The port number of the mail server to connect to.protected int
socket connection timeout value in milliseconds.protected int
socket I/O timeout value in milliseconds.protected boolean
Deprecated.since 1.3, use setSSLOnConnect() insteadprotected String
The port number of the SSL enabled SMTP server; defaults to the standard port, 465.protected String
The Subject.static final String
Deprecated.since 1.3, useEmailConstants.TEXT_HTML
insteadstatic final String
Deprecated.since 1.3, useEmailConstants.TEXT_PLAIN
insteadprotected boolean
Deprecated.since 1.3, use setStartTLSEnabled() insteadprotected List<javax.mail.internet.InternetAddress>
List of "to" email addresses.static final String
Deprecated.since 1.3, useEmailConstants.US_ASCII
instead -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionAdd a blind BCC recipient to the email.Add an array of blind BCC recipients to the email.Add a blind BCC recipient to the email using the specified address and the specified personal name.Add a blind BCC recipient to the email using the specified address, personal name, and charset encoding for the name.Add a recipient CC to the email.Add an array of CC recipients to the email.Add a recipient CC to the email using the specified address and the specified personal name.Add a recipient CC to the email using the specified address, personal name, and charset encoding for the name.void
Adds a header ( name, value ) to the headers Map.addReplyTo
(String email) Add a reply to address to the email.addReplyTo
(String email, String name) Add a reply to address to the email using the specified address and the specified personal name.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.Add a recipient TO to the email.Add a list of TO recipients to the email.Add a recipient TO to the email using the specified address and the specified personal name.Add a recipient TO to the email using the specified address, personal name, and charset encoding for the name.void
Does the work of actually building the MimeMessage.protected javax.mail.internet.MimeMessage
createMimeMessage
(javax.mail.Session aSession) Factory method to create a customized MimeMessage which can be implemented by a derived class, e.g.List<javax.mail.internet.InternetAddress>
Get the list of "Bcc" addresses.Gets the "bounce address" of this email.List<javax.mail.internet.InternetAddress>
Get the list of "CC" addresses.javax.mail.internet.InternetAddress
Gets the sender of the email.Gets the specified header.Gets all headers on an Email.Gets the host name of the SMTP server,javax.mail.Session
Determines the mail session used when sending this Email, creating the Session if necessary.javax.mail.internet.MimeMessage
Returns the internal MimeMessage.List<javax.mail.internet.InternetAddress>
Get the list of "Reply-To" addresses.Gets the sent date for the email.Gets the listening port of the SMTP server.int
Get the socket connection timeout value in milliseconds.int
Get the socket I/O timeout value in milliseconds.Returns the current SSL port used by the SMTP transport.Gets the subject of the email.List<javax.mail.internet.InternetAddress>
Get the list of "To" addresses.boolean
If partial sending of email enabled.boolean
isSSL()
Deprecated.since 1.3, use isSSLOnConnect() insteadboolean
Is the server identity checked as specified by RFC 2595boolean
Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).boolean
Gets whether the client is configured to try to enable STARTTLS.boolean
Gets whether the client is configured to require STARTTLS.boolean
isTLS()
Deprecated.since 1.3, use isStartTLSEnabled() insteadsend()
Sends the email.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
(javax.mail.Authenticator newAuthenticator) Sets theAuthenticator
to be used when authentication is requested from the mail server.setBcc
(Collection<javax.mail.internet.InternetAddress> aCollection) Set a list of "BCC" addresses.setBounceAddress
(String email) Set the "bounce address" - the address to which undeliverable messages will be returned.setCc
(Collection<javax.mail.internet.InternetAddress> aCollection) Set a list of "CC" addresses.void
setCharset
(String newCharset) Set the charset of the message.void
setContent
(Object aObject, String aContentType) Set the content and contentType.void
setContent
(javax.mail.internet.MimeMultipart aMimeMultipart) Set the emailBody to a MimeMultiPartvoid
setDebug
(boolean d) Setting to true will enable the display of debug information.Set the FROM field of the email to use the specified address.Set the FROM field of the email to use the specified address and the specified personal name.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
(javax.mail.Session aSession) Supply a mail Session object to use.void
setMailSessionFromJNDI
(String jndiName) Supply a mail Session object from a JNDI directory.abstract Email
Define the content of the mail.void
setPopBeforeSmtp
(boolean newPopBeforeSmtp, String newPopHost, String newPopUsername, String newPopPassword) Set details regarding "pop3 before smtp" authentication.setReplyTo
(Collection<javax.mail.internet.InternetAddress> aCollection) Set a list of reply to addresses.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() insteadsetSSLCheckServerIdentity
(boolean sslCheckServerIdentity) Sets whether the server identity is checked as specified by RFC 2595setSSLOnConnect
(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.setStartTLSEnabled
(boolean startTlsEnabled) Set or disable the STARTTLS encryption.setStartTLSRequired
(boolean startTlsRequired) Set or disable the required STARTTLS encryption.setSubject
(String aSubject) Sets the email subject.void
setTLS
(boolean withTLS) Deprecated.since 1.3, use setStartTLSEnabled() insteadsetTo
(Collection<javax.mail.internet.InternetAddress> aCollection) Set a list of "TO" addresses.protected javax.mail.internet.InternetAddress[]
toInternetAddressArray
(List<javax.mail.internet.InternetAddress> list) Utility to copy List of known InternetAddress objects into an array.void
updateContentType
(String aContentType) Update the contentType.
-
Field Details
-
SENDER_EMAIL
Deprecated.since 1.3, useEmailConstants.SENDER_EMAIL
instead- See Also:
-
SENDER_NAME
Deprecated.since 1.3, useEmailConstants.SENDER_NAME
instead- See Also:
-
RECEIVER_EMAIL
Deprecated.since 1.3, useEmailConstants.RECEIVER_EMAIL
instead- See Also:
-
RECEIVER_NAME
Deprecated.since 1.3, useEmailConstants.RECEIVER_NAME
instead- See Also:
-
EMAIL_SUBJECT
Deprecated.since 1.3, useEmailConstants.EMAIL_SUBJECT
instead- See Also:
-
EMAIL_BODY
Deprecated.since 1.3, useEmailConstants.EMAIL_BODY
instead- See Also:
-
CONTENT_TYPE
Deprecated.since 1.3, useEmailConstants.CONTENT_TYPE
instead- See Also:
-
ATTACHMENTS
Deprecated.since 1.3, useEmailConstants.ATTACHMENTS
instead- See Also:
-
FILE_SERVER
Deprecated.since 1.3, useEmailConstants.FILE_SERVER
instead- See Also:
-
KOI8_R
Deprecated.since 1.3, useEmailConstants.KOI8_R
instead- See Also:
-
ISO_8859_1
Deprecated.since 1.3, useEmailConstants.ISO_8859_1
instead- See Also:
-
US_ASCII
Deprecated.since 1.3, useEmailConstants.US_ASCII
instead- See Also:
-
MAIL_DEBUG
Deprecated.since 1.3, useEmailConstants.MAIL_DEBUG
instead- See Also:
-
MAIL_HOST
Deprecated.since 1.3, useEmailConstants.MAIL_HOST
instead- See Also:
-
MAIL_PORT
Deprecated.since 1.3, useEmailConstants.MAIL_PORT
instead- See Also:
-
MAIL_SMTP_FROM
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_FROM
instead- See Also:
-
MAIL_SMTP_AUTH
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_AUTH
instead- See Also:
-
MAIL_SMTP_USER
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_USER
instead- See Also:
-
MAIL_SMTP_PASSWORD
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_PASSWORD
instead- See Also:
-
MAIL_TRANSPORT_PROTOCOL
Deprecated.since 1.3, useEmailConstants.MAIL_TRANSPORT_PROTOCOL
instead- See Also:
-
SMTP
Deprecated.since 1.3, useEmailConstants.SMTP
instead- See Also:
-
TEXT_HTML
Deprecated.since 1.3, useEmailConstants.TEXT_HTML
instead- See Also:
-
TEXT_PLAIN
Deprecated.since 1.3, useEmailConstants.TEXT_PLAIN
instead- See Also:
-
MAIL_TRANSPORT_TLS
Deprecated.since 1.3, useEmailConstants.MAIL_TRANSPORT_TLS
instead- See Also:
-
MAIL_SMTP_SOCKET_FACTORY_FALLBACK
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_FALLBACK
instead- See Also:
-
MAIL_SMTP_SOCKET_FACTORY_CLASS
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_CLASS
instead- See Also:
-
MAIL_SMTP_SOCKET_FACTORY_PORT
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_SOCKET_FACTORY_PORT
instead- See Also:
-
MAIL_SMTP_CONNECTIONTIMEOUT
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_CONNECTIONTIMEOUT
instead- See Also:
-
MAIL_SMTP_TIMEOUT
Deprecated.since 1.3, useEmailConstants.MAIL_SMTP_TIMEOUT
instead- See Also:
-
message
The email message to send. -
charset
The charset to use for this message. -
fromAddress
The Address of the sending party, mandatory. -
subject
The Subject. -
emailBody
An attachment. -
The content.
-
contentType
The content type. -
debug
Set session debugging on or off. -
sentDate
Sent date. -
authenticator
Instance of anAuthenticator
object that will be used when authentication is requested from the mail server. -
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
The port number of the mail server to connect to. Defaults to the standard port ( 25 ). -
sslSmtpPort
The port number of the SSL enabled SMTP server; defaults to the standard port, 465. -
toList
List of "to" email addresses. -
ccList
List of "cc" email addresses. -
bccList
List of "bcc" email addresses. -
replyList
List of "replyTo" email addresses. -
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 typeString
rather thanInternetAddress
. -
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
Used to determine whether to use pop3 before smtp, and if so the settings. -
popHost
the host name of the pop3 server. -
popUsername
the user name to log into the pop3 server. -
popPassword
the password to log into the pop3 server. -
tls
Deprecated.since 1.3, use setStartTLSEnabled() insteadDoes server require TLS encryption for authentication? -
ssl
Deprecated.since 1.3, use setSSLOnConnect() insteadDoes the current transport use SSL/TLS encryption upon connection? -
socketTimeout
socket I/O timeout value in milliseconds. -
socketConnectionTimeout
socket connection timeout value in milliseconds.
-
-
Constructor Details
-
Email
public Email()
-
-
Method Details
-
setDebug
Setting to true will enable the display of debug information.- Parameters:
d
- A boolean.- Since:
- 1.0
-
setAuthentication
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 serverpassword
- password for the SMTP server- Since:
- 1.0
- See Also:
-
setAuthenticator
Sets theAuthenticator
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
- theAuthenticator
object.- Since:
- 1.0
- See Also:
-
Authenticator
-
setCharset
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 invalidUnsupportedCharsetException
- if no support for the named charset exists in the current JVM- Since:
- 1.0
-
setContent
Set the emailBody to a MimeMultiPart- Parameters:
aMimeMultipart
- aMimeMultipart- Since:
- 1.0
-
setContent
Set the content and contentType.- Parameters:
aObject
- aObjectaContentType
- aContentType- Since:
- 1.0
-
updateContentType
Update the contentType.- Parameters:
aContentType
- aContentType- Since:
- 1.2
-
setHostName
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.since 1.3, use setStartTLSEnabled() insteadSet 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
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
Set or disable the required STARTTLS encryption.Defaults to
smtpPort
; can be overridden by usingsetSmtpPort(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
Set the non-SSL port number of the outgoing mail server.- Parameters:
aPortNumber
- aPortNumber- Throws:
IllegalArgumentException
- if the port number is < 1IllegalStateException
- if the mail session is already initialized- Since:
- 1.0
- See Also:
-
setMailSession
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 isnull
- Since:
- 1.0
-
setMailSessionFromJNDI
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 emptyNamingException
- if the resource cannot be retrieved from JNDI directory- Since:
- 1.1
-
getMailSession
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
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
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
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
Add a recipient TO to the email using the specified address and the specified personal name. The name will be encoded by the charset ofsetCharset()
. 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
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<javax.mail.internet.InternetAddress> aCollection) throws EmailException Set a list of "TO" addresses. All elements in the specifiedCollection
are expected to be of typejava.mail.internet.InternetAddress
.- Parameters:
aCollection
- collection ofInternetAddress
objects.- Returns:
- An Email.
- Throws:
EmailException
- Indicates an invalid email address.- Since:
- 1.0
- See Also:
-
InternetAddress
-
addCc
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
Add a recipient CC to the email using the specified address and the specified personal name. The name will be encoded by the charset ofsetCharset()
. 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
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<javax.mail.internet.InternetAddress> aCollection) throws EmailException Set a list of "CC" addresses. All elements in the specifiedCollection
are expected to be of typejava.mail.internet.InternetAddress
.- Parameters:
aCollection
- collection ofInternetAddress
objects.- Returns:
- An Email.
- Throws:
EmailException
- Indicates an invalid email address.- Since:
- 1.0
- See Also:
-
InternetAddress
-
addBcc
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
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<javax.mail.internet.InternetAddress> aCollection) throws EmailException Set a list of "BCC" addresses. All elements in the specifiedCollection
are expected to be of typejava.mail.internet.InternetAddress
.- Parameters:
aCollection
- collection ofInternetAddress
objects- Returns:
- An Email.
- Throws:
EmailException
- Indicates an invalid email address- Since:
- 1.0
- See Also:
-
InternetAddress
-
addReplyTo
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 ofsetCharset()
. 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
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 ofsetCharset()
. 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
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<javax.mail.internet.InternetAddress> aCollection) throws EmailException Set a list of reply to addresses. All elements in the specifiedCollection
are expected to be of typejava.mail.internet.InternetAddress
.- Parameters:
aCollection
- collection ofInternetAddress
objects- Returns:
- An Email.
- Throws:
EmailException
- Indicates an invalid email address- Since:
- 1.1
- See Also:
-
InternetAddress
-
setHeaders
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
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 eithername
orvalue
is null or empty- Since:
- 1.0
-
getHeader
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
Gets all headers on an Email.- Returns:
- a Map of all headers.
- Since:
- 1.5
-
setSubject
Sets the email subject. Replaces end-of-line characters with spaces.- Parameters:
aSubject
- A String.- Returns:
- An Email.
- Since:
- 1.0
-
getBounceAddress
Gets the "bounce address" of this email.- Returns:
- the bounce address as string
- Since:
- 1.4
-
setBounceAddress
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
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
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 builtEmailException
- if there was an error.- Since:
- 1.0
-
sendMimeMessage
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 createdEmailException
- the sending failed
-
getMimeMessage
Returns the internal MimeMessage. Please note that the MimeMessage is built by the buildMimeMessage() method.- Returns:
- the MimeMessage
-
send
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, iebuildMimeMessage()
was already calledEmailException
- the sending failed
-
setSentDate
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
Gets the sent date for the email.- Returns:
- date to be used as the sent date for the email
- Since:
- 1.0
-
getSubject
Gets the subject of the email.- Returns:
- email subject
-
getFromAddress
Gets the sender of the email.- Returns:
- from address
-
getHostName
Gets the host name of the SMTP server,- Returns:
- host name
-
getSmtpPort
Gets the listening port of the SMTP server.- Returns:
- smtp port
-
isStartTLSRequired
Gets whether the client is configured to require STARTTLS.- Returns:
- true if using STARTTLS for authentication, false otherwise
- Since:
- 1.3
-
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.since 1.3, use isStartTLSEnabled() insteadGets 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 javax.mail.internet.InternetAddress[] toInternetAddressArray(List<javax.mail.internet.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.since 1.3, use isSSLOnConnect() insteadReturns 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
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.since 1.3, use setSSLOnConnect() insteadSets 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
Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS). Takes precedence oversetStartTLSRequired(boolean)
Defaults to
sslSmtpPort
; can be overridden by usingsetSslSmtpPort(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
Is the server identity checked as specified by RFC 2595- Returns:
- true if the server identity is checked
- Since:
- 1.3
-
setSSLCheckServerIdentity
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
Returns the current SSL port used by the SMTP transport.- Returns:
- the current SSL port used by the SMTP transport
-
setSslSmtpPort
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:
-
isSendPartial
If partial sending of email enabled.- Returns:
- true if sending partial email is enabled
- Since:
- 1.3.2
-
setSendPartial
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 aSendFailedException
, 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 thesend()
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
Get the list of "To" addresses.- Returns:
- List addresses
-
getCcAddresses
Get the list of "CC" addresses.- Returns:
- List addresses
-
getBccAddresses
Get the list of "Bcc" addresses.- Returns:
- List addresses
-
getReplyToAddresses
Get the list of "Reply-To" addresses.- Returns:
- List addresses
-
getSocketConnectionTimeout
Get the socket connection timeout value in milliseconds.- Returns:
- the timeout in milliseconds.
- Since:
- 1.2
-
setSocketConnectionTimeout
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
Get the socket I/O timeout value in milliseconds.- Returns:
- the socket I/O timeout
- Since:
- 1.2
-
setSocketTimeout
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
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
-
EmailConstants.ATTACHMENTS
instead