Package org.apache.commons.mail

Class Email

  • Direct Known Subclasses:
    MultiPartEmail, SimpleEmail
    public abstract class Email
extends java.lang.Object
    The abstract class for all email messages. This class sets the sender's email, name, receiver's email, name, subject, and send date.

    Subclasses are responsible for setting the message body.

    Since:
    1.0

    • Constructor Detail

      • Email

        public Email()
        Constructs a new instance.

    • Method Detail

      • addBcc

        public Email addBcc​(java.lang.String email)
             throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.0

      • addBcc

        public Email addBcc​(java.lang.String... emails)
             throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        emails - A String array.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.3

      • addBcc

        public Email addBcc​(java.lang.String email,
                    java.lang.String name)
             throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        name - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.0

      • addBcc

        public Email addBcc​(java.lang.String email,
                    java.lang.String name,
                    java.lang.String charset)
             throws EmailException
        Adds 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

      • addCc

        public Email addCc​(java.lang.String email)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • addCc

        public Email addCc​(java.lang.String... emails)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        emails - A String array.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.3

      • addCc

        public Email addCc​(java.lang.String email,
                   java.lang.String name)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        name - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • addCc

        public Email addCc​(java.lang.String email,
                   java.lang.String name,
                   java.lang.String charset)
            throws EmailException
        Adds 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

      • addHeader

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

      • addReplyTo

        public Email addReplyTo​(java.lang.String email)
                 throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.0

      • addReplyTo

        public Email addReplyTo​(java.lang.String email,
                        java.lang.String name)
                 throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        name - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.0

      • addReplyTo

        public Email addReplyTo​(java.lang.String email,
                        java.lang.String name,
                        java.lang.String charset)
                 throws EmailException
        Adds 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

      • addTo

        public Email addTo​(java.lang.String email)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • addTo

        public Email addTo​(java.lang.String... emails)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        emails - A String array.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.3

      • addTo

        public Email addTo​(java.lang.String email,
                   java.lang.String name)
            throws EmailException
        Adds 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        name - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • addTo

        public Email addTo​(java.lang.String email,
                   java.lang.String name,
                   java.lang.String charset)
            throws EmailException
        Adds 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

      • buildMimeMessage

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

      • createMimeMessage

        protected javax.mail.internet.MimeMessage createMimeMessage​(javax.mail.Session aSession)
        Creates 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

      • getAuthenticator

        public javax.mail.Authenticator getAuthenticator()
        Gets the authenticator.
        Returns:
        the authenticator.
        Since:
        1.6.0

      • getBccAddresses

        public java.util.List<javax.mail.internet.InternetAddress> getBccAddresses()
        Gets the list of "Bcc" addresses.
        Returns:
        List addresses

      • getBounceAddress

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

      • getCcAddresses

        public java.util.List<javax.mail.internet.InternetAddress> getCcAddresses()
        Gets the list of "CC" addresses.
        Returns:
        List addresses

      • getCharsetName

        public java.lang.String getCharsetName()
        Gets the Charset.
        Returns:
        the Charset.
        Since:
        1.6.0

      • getContent

        public java.lang.Object getContent()
        Gets the content.
        Returns:
        the content.
        Since:
        1.6.0

      • getContentType

        public java.lang.String getContentType()
        Gets the content type.
        Returns:
        the content type.
        Since:
        1.6.0

      • getEmailBody

        public javax.mail.internet.MimeMultipart getEmailBody()
        Gets the email body.
        Returns:
        the email body.
        Since:
        1.6.0

      • getFromAddress

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

      • getHeader

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

      • getHeaders

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

      • getHostName

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

      • getMailSession

        public javax.mail.Session getMailSession()
                                  throws EmailException
        Gets 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

      • getMessage

        public javax.mail.internet.MimeMessage getMessage()
        Gets the message.
        Returns:
        the message.
        Since:
        1.6.0

      • getMimeMessage

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

      • getPopHost

        public java.lang.String getPopHost()
        Gets the POP3 host.
        Returns:
        the POP3 host.
        Since:
        1.6.0

      • getPopPassword

        public java.lang.String getPopPassword()
        Gets the POP3 password.
        Returns:
        the POP3 password.
        Since:
        1.6.0

      • getPopUserName

        public java.lang.String getPopUserName()
        Gets the POP3 user name.
        Returns:
        the POP3 user name.
        Since:
        1.6.0

      • getReplyToAddresses

        public java.util.List<javax.mail.internet.InternetAddress> getReplyToAddresses()
        Gets the list of "Reply-To" addresses.
        Returns:
        List addresses

      • getSentDate

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

      • getSmtpPort

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

      • getSocketConnectionTimeout

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

      • getSocketTimeout

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

      • getSslSmtpPort

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

      • getSubject

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

      • getToAddresses

        public java.util.List<javax.mail.internet.InternetAddress> getToAddresses()
        Gets the list of "To" addresses.
        Returns:
        List addresses

      • isDebug

        public boolean isDebug()
        Tests whether debug is on.
        Returns:
        whether debug is on.
        Since:
        1.6.0

      • isPopBeforeSmtp

        public boolean isPopBeforeSmtp()
        Tests whether to use POP3 before SMTP, and if so the settings.
        Returns:
        whether to use POP3 before SMTP, and if so the settings.
        Since:
        1.6.0

      • isSendPartial

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

      • isSSL

        @Deprecated
public boolean isSSL()
        Deprecated.
        since 1.3, use isSSLOnConnect() instead.
        Tests 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.

      • isSSLCheckServerIdentity

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

      • isSSLOnConnect

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

      • isStartTLSEnabled

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

      • isStartTLSRequired

        public boolean isStartTLSRequired()
        Tests whether the client is configured to require 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.
        Tests 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

      • send

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

      • sendMimeMessage

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

      • setAuthentication

        public void setAuthentication​(java.lang.String userName,
                              java.lang.String password)
        Sets the userName and password if authentication is needed. If this method is not used, no authentication will be performed.

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

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

      • setAuthenticator

        public void setAuthenticator​(javax.mail.Authenticator authenticator)
        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:
        authenticator - the Authenticator object.
        Since:
        1.0
        See Also:
        Authenticator

      • setBcc

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

      • setBounceAddress

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

      • setCc

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

      • setCharset

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

      • setContent

        public void setContent​(javax.mail.internet.MimeMultipart mimeMultipart)
        Sets the emailBody to a MimeMultiPart
        Parameters:
        mimeMultipart - aMimeMultipart
        Since:
        1.0

      • setContent

        public Email setContent​(java.lang.Object content)
        Sets the content.
        Parameters:
        content - the content.
        Returns:
        this.
        Since:
        1.6.0

      • setContent

        public void setContent​(java.lang.Object content,
                       java.lang.String contentType)
        Sets the content and contentType.
        Parameters:
        content - content.
        contentType - content type.
        Since:
        1.0

      • setContentType

        public Email setContentType​(java.lang.String contentType)
        Sets the content type.
        Parameters:
        contentType - the content type.
        Returns:
        this.
        Since:
        1.6.0

      • setDebug

        public void setDebug​(boolean debug)
        Sets the display of debug information.
        Parameters:
        debug - A boolean.
        Since:
        1.0

      • setFrom

        public Email setFrom​(java.lang.String email)
              throws EmailException
        Sets 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • setFrom

        public Email setFrom​(java.lang.String email,
                     java.lang.String name)
              throws EmailException
        Sets 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(String). If it is not set, it will be encoded using the Java platform's default charset (UTF-16) if it contains non-ASCII characters; otherwise, it is used as is.
        Parameters:
        email - A String.
        name - A String.
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address.
        Since:
        1.0

      • setFrom

        public Email setFrom​(java.lang.String email,
                     java.lang.String name,
                     java.lang.String charset)
              throws EmailException
        Sets 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

      • setFromAddress

        public Email setFromAddress​(javax.mail.internet.InternetAddress fromAddress)
        Sets the From address.
        Parameters:
        fromAddress - the From address.
        Returns:
        this.
        Since:
        1.6.0

      • setHeaders

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

      • setHostName

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

      • setMailSession

        public void setMailSession​(javax.mail.Session session)
        Sets 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 user name and password is supplied the implementation assumes that you have set a authenticator and will use the existing mail session (as expected).
        Parameters:
        session - mail session to be used
        Throws:
        java.lang.NullPointerException - if aSession is null
        Since:
        1.0

      • setMailSessionFromJNDI

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

      • setMessage

        public void setMessage​(javax.mail.internet.MimeMessage message)
        Sets the MIME message.
        Parameters:
        message - the MIME message.

      • setMsg

        public abstract Email setMsg​(java.lang.String msg)
                      throws EmailException
        Sets 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

      • setPopBeforeSmtp

        public Email setPopBeforeSmtp​(boolean popBeforeSmtp)
        Sets whether to use POP3 before SMTP, and if so the settings.
        Parameters:
        popBeforeSmtp - whether to use POP3 before SMTP, and if so the settings.
        Returns:
        this.
        Since:
        1.6.0

      • setPopBeforeSmtp

        public void setPopBeforeSmtp​(boolean popBeforeSmtp,
                             java.lang.String popHost,
                             java.lang.String popUserName,
                             java.lang.String popPassword)
        Sets details regarding "POP3 before SMTP" authentication.
        Parameters:
        popBeforeSmtp - Whether or not to log into POP3 server before sending mail.
        popHost - The POP3 host to use.
        popUserName - The POP3 user name.
        popPassword - The POP3 password.
        Since:
        1.0

      • setPopHost

        public Email setPopHost​(java.lang.String popHost)
        Sets the POP3 host.
        Parameters:
        popHost - The POP3 host.
        Returns:
        this.
        Since:
        1.6.0

      • setPopPassword

        public Email setPopPassword​(java.lang.String popPassword)
        Sets the POP3 password.
        Parameters:
        popPassword - the POP3 password.
        Returns:
        this.
        Since:
        1.6.0

      • setPopUsername

        public Email setPopUsername​(java.lang.String popUserName)
        Sets the POP3 user name.
        Parameters:
        popUserName - the POP3 user name.
        Returns:
        this.
        Since:
        1.6.0

      • setReplyTo

        public Email setReplyTo​(java.util.Collection<javax.mail.internet.InternetAddress> collection)
                 throws EmailException
        Sets a list of reply to addresses. All elements in the specified Collection are expected to be of type java.mail.internet.InternetAddress.
        Parameters:
        collection - collection of InternetAddress objects
        Returns:
        An Email.
        Throws:
        EmailException - Indicates an invalid email address
        Since:
        1.1
        See Also:
        InternetAddress

      • setSendPartial

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

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

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

      • setSentDate

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

      • setSmtpPort

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

      • setSocketConnectionTimeout

        public void setSocketConnectionTimeout​(java.time.Duration socketConnectionTimeout)
        Sets the socket connection timeout value in milliseconds. Default is a 60 second timeout.
        Parameters:
        socketConnectionTimeout - the connection timeout
        Throws:
        java.lang.IllegalStateException - if the mail session is already initialized
        Since:
        1.6.0

      • setSocketConnectionTimeout

        @Deprecated
public void setSocketConnectionTimeout​(int socketConnectionTimeout)
        Deprecated.
        Use setSocketConnectionTimeout(Duration).
        Sets the socket connection timeout value in milliseconds. Default is a 60 second timeout.
        Parameters:
        socketConnectionTimeout - the connection timeout
        Throws:
        java.lang.IllegalStateException - if the mail session is already initialized
        Since:
        1.2

      • setSocketTimeout

        public void setSocketTimeout​(java.time.Duration socketTimeout)
        Sets the socket I/O timeout value in milliseconds. Default is 60 second timeout.
        Parameters:
        socketTimeout - the socket I/O timeout
        Throws:
        java.lang.IllegalStateException - if the mail session is already initialized
        Since:
        1.6.0

      • setSocketTimeout

        @Deprecated
public void setSocketTimeout​(int socketTimeout)
        Deprecated.
        Use setSocketTimeout(Duration).
        Sets the socket I/O timeout value in milliseconds. Default is 60 second timeout.
        Parameters:
        socketTimeout - the socket I/O timeout
        Throws:
        java.lang.IllegalStateException - if the mail session is already initialized
        Since:
        1.2

      • setSSL

        @Deprecated
public void setSSL​(boolean ssl)
        Deprecated.
        since 1.3, use setSSLOnConnect(boolean) 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

      • setSSLCheckServerIdentity

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

      • setSSLOnConnect

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

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

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

      • setSslSmtpPort

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

      • setStartTLSEnabled

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

      • setStartTLSRequired

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

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

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

      • setSubject

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

      • setTLS

        @Deprecated
public void setTLS​(boolean withTLS)
        Deprecated.
        since 1.3, use setStartTLSEnabled(boolean) instead.
        Sets 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

      • setTo

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

      • toInternetAddressArray

        protected javax.mail.internet.InternetAddress[] toInternetAddressArray​(java.util.List<javax.mail.internet.InternetAddress> list)
        Converts to copy List of known InternetAddress objects into an array.
        Parameters:
        list - A List.
        Returns:
        An InternetAddress[].
        Since:
        1.0

      • updateContentType

        public void updateContentType​(java.lang.String contentType)
        Updates the contentType.
        Parameters:
        contentType - aContentType
        Since:
        1.2