Package org.apache.commons.mail

Class Email

java.lang.Object
org.apache.commons.mail.Email
Direct Known Subclasses:
MultiPartEmail, SimpleEmail
public abstract class Email extends Object
The base class for all email messages. This class sets the sender's email & name, receiver's email & name, subject, and the sent date.

Subclasses are responsible for setting the message body.

Since:
1.0

  • Field Details

  • Constructor Details

    • Email

      public Email()

  • Method Details

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

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

    • setCharset

      public void setCharset(String newCharset)
      Set the charset of the message. Please note that you should set the charset before adding the message content.
      Parameters:
      newCharset - A String.
      Throws:
      IllegalCharsetNameException - if the charset name is invalid
      UnsupportedCharsetException - if no support for the named charset exists in the current JVM
      Since:
      1.0

    • setContent

      public void setContent(MimeMultipart aMimeMultipart)
      Set the emailBody to a MimeMultiPart
      Parameters:
      aMimeMultipart - aMimeMultipart
      Since:
      1.0

    • setContent

      public void setContent(Object aObject, String aContentType)
      Set the content and contentType.
      Parameters:
      aObject - aObject
      aContentType - aContentType
      Since:
      1.0

    • updateContentType

      public void updateContentType(String aContentType)
      Update the contentType.
      Parameters:
      aContentType - aContentType
      Since:
      1.2

    • setHostName

      public void setHostName(String aHostName)
      Set the hostname of the outgoing mail server.
      Parameters:
      aHostName - aHostName
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.0

    • setTLS

      @Deprecated public void setTLS(boolean withTLS)
      Deprecated.
      since 1.3, use setStartTLSEnabled() instead
      Set or disable the STARTTLS encryption. Please see EMAIL-105 for the reasons of deprecation.
      Parameters:
      withTLS - true if STARTTLS requested, false otherwise
      Since:
      1.1

    • setStartTLSEnabled

      public Email setStartTLSEnabled(boolean startTlsEnabled)
      Set or disable the STARTTLS encryption.
      Parameters:
      startTlsEnabled - true if STARTTLS requested, false otherwise
      Returns:
      An Email.
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.3

    • setStartTLSRequired

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

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

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

    • setSmtpPort

      public void setSmtpPort(int aPortNumber)
      Set the non-SSL port number of the outgoing mail server.
      Parameters:
      aPortNumber - aPortNumber
      Throws:
      IllegalArgumentException - if the port number is < 1
      IllegalStateException - if the mail session is already initialized
      Since:
      1.0
      See Also:

    • setMailSession

      public void setMailSession(Session aSession)
      Supply a mail Session object to use. Please note that passing a user name and password (in the case of mail authentication) will create a new mail session with a DefaultAuthenticator. This is a convenience but might come unexpected. If mail authentication is used but NO username and password is supplied the implementation assumes that you have set a authenticator and will use the existing mail session (as expected).
      Parameters:
      aSession - mail session to be used
      Throws:
      IllegalArgumentException - if the session is null
      Since:
      1.0

    • setMailSessionFromJNDI

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

    • getMailSession

      public Session getMailSession() throws EmailException
      Determines the mail session used when sending this Email, creating the Session if necessary. When a mail session is already initialized setting the session related properties will cause an IllegalStateException.
      Returns:
      A Session.
      Throws:
      EmailException - if the host name was not set
      Since:
      1.0

    • setFrom

      public Email setFrom(String email) throws EmailException
      Set the FROM field of the email to use the specified address. The email address will also be used as the personal name. The name will be encoded by the charset of setCharset(). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
      Parameters:
      email - A String.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.0

    • setFrom

      public Email setFrom(String email, String name) throws EmailException
      Set the FROM field of the email to use the specified address and the specified personal name. The name will be encoded by the charset of setCharset(). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
      Parameters:
      email - A String.
      name - A String.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.0

    • setFrom

      public Email setFrom(String email, String name, String charset) throws EmailException
      Set the FROM field of the email to use the specified address, personal name, and charset encoding for the name.
      Parameters:
      email - A String.
      name - A String.
      charset - The charset to encode the name with.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address or charset.
      Since:
      1.1

    • addTo

      public Email addTo(String email) throws EmailException
      Add a recipient TO to the email. The email address will also be used as the personal name. The name will be encoded by the charset of setCharset(). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
      Parameters:
      email - A String.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.0

    • addTo

      public Email addTo(String... emails) throws EmailException
      Add a list of TO recipients to the email. The email addresses will also be used as the personal names. The names will be encoded by the charset of setCharset(). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
      Parameters:
      emails - A String array.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.3

    • addTo

      public Email addTo(String email, String name) throws EmailException
      Add a recipient TO to the email using the specified address and the specified personal name. The name will be encoded by the charset of setCharset(). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
      Parameters:
      email - A String.
      name - A String.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.0

    • addTo

      public Email addTo(String email, String name, String charset) throws EmailException
      Add a recipient TO to the email using the specified address, personal name, and charset encoding for the name.
      Parameters:
      email - A String.
      name - A String.
      charset - The charset to encode the name with.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address or charset.
      Since:
      1.1

    • setTo

      public Email setTo(Collection<InternetAddress> aCollection) throws EmailException
      Set a list of "TO" addresses. All elements in the specified Collection are expected to be of type java.mail.internet.InternetAddress.
      Parameters:
      aCollection - collection of InternetAddress objects.
      Returns:
      An Email.
      Throws:
      EmailException - Indicates an invalid email address.
      Since:
      1.0
      See Also:

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

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

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

    • setHeaders

      public void setHeaders(Map<String,String> map)
      Used to specify the mail headers. Example: X-Mailer: Sendmail, X-Priority: 1( highest ) or 2( high ) 3( normal ) 4( low ) and 5( lowest ) Disposition-Notification-To: user@domain.net
      Parameters:
      map - A Map.
      Throws:
      IllegalArgumentException - if either of the provided header / value is null or empty
      Since:
      1.0

    • addHeader

      public void addHeader(String name, String value)
      Adds a header ( name, value ) to the headers Map.
      Parameters:
      name - A String with the name.
      value - A String with the value.
      Throws:
      IllegalArgumentException - if either name or value is null or empty
      Since:
      1.0

    • getHeader

      public String getHeader(String header)
      Gets the specified header.
      Parameters:
      header - A string with the header.
      Returns:
      The value of the header, or null if no such header.
      Since:
      1.5

    • getHeaders

      public Map<String,String> getHeaders()
      Gets all headers on an Email.
      Returns:
      a Map of all headers.
      Since:
      1.5

    • setSubject

      public Email setSubject(String aSubject)
      Sets the email subject. Replaces end-of-line characters with spaces.
      Parameters:
      aSubject - A String.
      Returns:
      An Email.
      Since:
      1.0

    • getBounceAddress

      public String getBounceAddress()
      Gets the "bounce address" of this email.
      Returns:
      the bounce address as string
      Since:
      1.4

    • setBounceAddress

      public Email setBounceAddress(String email)
      Set the "bounce address" - the address to which undeliverable messages will be returned. If this value is never set, then the message will be sent to the address specified with the System property "mail.smtp.from", or if that value is not set, then to the "from" address.
      Parameters:
      email - A String.
      Returns:
      An Email.
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.0

    • setMsg

      public abstract Email setMsg(String msg) throws EmailException
      Define the content of the mail. It should be overridden by the subclasses.
      Parameters:
      msg - A String.
      Returns:
      An Email.
      Throws:
      EmailException - generic exception.
      Since:
      1.0

    • buildMimeMessage

      public void buildMimeMessage() throws EmailException
      Does the work of actually building the MimeMessage. Please note that a user rarely calls this method directly and only if he/she is interested in the sending the underlying MimeMessage without commons-email.
      Throws:
      IllegalStateException - if the MimeMessage was already built
      EmailException - if there was an error.
      Since:
      1.0

    • sendMimeMessage

      public String sendMimeMessage() throws EmailException
      Sends the previously created MimeMessage to the SMTP server.
      Returns:
      the message id of the underlying MimeMessage
      Throws:
      IllegalArgumentException - if the MimeMessage has not been created
      EmailException - the sending failed

    • getMimeMessage

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

    • send

      public String send() throws EmailException
      Sends the email. Internally we build a MimeMessage which is afterwards sent to the SMTP server.
      Returns:
      the message id of the underlying MimeMessage
      Throws:
      IllegalStateException - if the MimeMessage was already built, ie buildMimeMessage() was already called
      EmailException - the sending failed

    • setSentDate

      public void setSentDate(Date date)
      Sets the sent date for the email. The sent date will default to the current date if not explicitly set.
      Parameters:
      date - Date to use as the sent date on the email
      Since:
      1.0

    • getSentDate

      public Date getSentDate()
      Gets the sent date for the email.
      Returns:
      date to be used as the sent date for the email
      Since:
      1.0

    • getSubject

      public String getSubject()
      Gets the subject of the email.
      Returns:
      email subject

    • getFromAddress

      public InternetAddress getFromAddress()
      Gets the sender of the email.
      Returns:
      from address

    • getHostName

      public String getHostName()
      Gets the host name of the SMTP server,
      Returns:
      host name

    • getSmtpPort

      public String getSmtpPort()
      Gets the listening port of the SMTP server.
      Returns:
      smtp port

    • isStartTLSRequired

      public boolean isStartTLSRequired()
      Gets whether the client is configured to require STARTTLS.
      Returns:
      true if using STARTTLS for authentication, false otherwise
      Since:
      1.3

    • isStartTLSEnabled

      public boolean isStartTLSEnabled()
      Gets whether the client is configured to try to enable STARTTLS.
      Returns:
      true if using STARTTLS for authentication, false otherwise
      Since:
      1.3

    • isTLS

      @Deprecated public boolean isTLS()
      Deprecated.
      since 1.3, use isStartTLSEnabled() instead
      Gets whether the client is configured to try to enable STARTTLS. See EMAIL-105 for reason of deprecation.
      Returns:
      true if using STARTTLS for authentication, false otherwise
      Since:
      1.1

    • setPopBeforeSmtp

      public void setPopBeforeSmtp(boolean newPopBeforeSmtp, String newPopHost, String newPopUsername, String newPopPassword)
      Set details regarding "pop3 before smtp" authentication.
      Parameters:
      newPopBeforeSmtp - Whether or not to log into pop3 server before sending mail.
      newPopHost - The pop3 host to use.
      newPopUsername - The pop3 username.
      newPopPassword - The pop3 password.
      Since:
      1.0

    • isSSL

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

    • isSSLOnConnect

      public boolean isSSLOnConnect()
      Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).
      Returns:
      true if SSL enabled for the transport
      Since:
      1.3

    • setSSL

      @Deprecated public void setSSL(boolean ssl)
      Deprecated.
      since 1.3, use setSSLOnConnect() instead
      Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection (SMTPS/POPS). See EMAIL-105 for reason of deprecation.
      Parameters:
      ssl - whether to enable the SSL transport

    • setSSLOnConnect

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

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

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

    • isSSLCheckServerIdentity

      public boolean isSSLCheckServerIdentity()
      Is the server identity checked as specified by RFC 2595
      Returns:
      true if the server identity is checked
      Since:
      1.3

    • setSSLCheckServerIdentity

      public Email setSSLCheckServerIdentity(boolean sslCheckServerIdentity)
      Sets whether the server identity is checked as specified by RFC 2595
      Parameters:
      sslCheckServerIdentity - whether to enable server identity check
      Returns:
      An Email.
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.3

    • getSslSmtpPort

      public String getSslSmtpPort()
      Returns the current SSL port used by the SMTP transport.
      Returns:
      the current SSL port used by the SMTP transport

    • setSslSmtpPort

      public void setSslSmtpPort(String sslSmtpPort)
      Sets the SSL port to use for the SMTP transport. Defaults to the standard port, 465.
      Parameters:
      sslSmtpPort - the SSL port to use for the SMTP transport
      Throws:
      IllegalStateException - if the mail session is already initialized
      See Also:

    • isSendPartial

      public boolean isSendPartial()
      If partial sending of email enabled.
      Returns:
      true if sending partial email is enabled
      Since:
      1.3.2

    • setSendPartial

      public Email setSendPartial(boolean sendPartial)
      Sets whether the email is partially send in case of invalid addresses.

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

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

    • getToAddresses

      public List<InternetAddress> getToAddresses()
      Get the list of "To" addresses.
      Returns:
      List addresses

    • getCcAddresses

      public List<InternetAddress> getCcAddresses()
      Get the list of "CC" addresses.
      Returns:
      List addresses

    • getBccAddresses

      public List<InternetAddress> getBccAddresses()
      Get the list of "Bcc" addresses.
      Returns:
      List addresses

    • getReplyToAddresses

      public List<InternetAddress> getReplyToAddresses()
      Get the list of "Reply-To" addresses.
      Returns:
      List addresses

    • getSocketConnectionTimeout

      public int getSocketConnectionTimeout()
      Get the socket connection timeout value in milliseconds.
      Returns:
      the timeout in milliseconds.
      Since:
      1.2

    • setSocketConnectionTimeout

      public void setSocketConnectionTimeout(int socketConnectionTimeout)
      Set the socket connection timeout value in milliseconds. Default is a 60 second timeout.
      Parameters:
      socketConnectionTimeout - the connection timeout
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.2

    • getSocketTimeout

      public int getSocketTimeout()
      Get the socket I/O timeout value in milliseconds.
      Returns:
      the socket I/O timeout
      Since:
      1.2

    • setSocketTimeout

      public void setSocketTimeout(int socketTimeout)
      Set the socket I/O timeout value in milliseconds. Default is 60 second timeout.
      Parameters:
      socketTimeout - the socket I/O timeout
      Throws:
      IllegalStateException - if the mail session is already initialized
      Since:
      1.2