com.sun.mail.smtp

## Class SMTPTransport

- java.lang.Object
- - javax.mail.Service
  - - javax.mail.Transport
    - - com.sun.mail.smtp.SMTPTransport

- Direct Known Subclasses:
    SMTPSSLTransport

      public class SMTPTransport
      extends Transport

  This class implements the Transport abstract class using SMTP for message submission and transport.

  See the com.sun.mail.smtp package documentation for further information on the SMTP protocol provider.

  This class includes many protected methods that allow a subclass to extend this class and add support for non-standard SMTP commands. The `issueCommand(java.lang.String, int)` and `sendCommand(java.lang.String)` methods can be used to send simple SMTP commands. Other methods such as the `mailFrom()` and `data()` methods can be overridden to insert new commands before or after the corresponding SMTP commands. For example, a subclass could do this to send the XACT command before sending the DATA command:

              protected OutputStream data() throws MessagingException {
                  if (supportsExtension("XACCOUNTING"))
                      issueCommand("XACT", 25);
                  return super.data();
              }

  Author:
    Max Spivak, Bill Shannon, Dean Gibson (DIGEST-MD5 authentication), Luís Serralheiro (NTLM authentication)
  See Also:
    `ConnectionEvent`, `TransportEvent`

- - ### Field Summary

    - ### Fields inherited from class javax.mail.Service

      `debug, session, url`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `SMTPTransport(Session session, URLName urlname)` Constructor that takes a Session object and a URLName that represents a specific SMTP server.
    `protected` | `SMTPTransport(Session session, URLName urlname, String name, boolean isSSL)` Constructor used by this class and by SMTPSSLTransport subclass.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkConnected()` Check if we're in the connected state.
    `void` | `close()` Close the Transport and terminate the connection to the server.
    `void` | `connect(Socket socket)` Start the SMTP protocol on the given socket, which was already connected by the caller.
    `protected OutputStream` | `data()` Send the `DATA` command to the SMTP host and return an OutputStream to which the data is to be written.
    `protected boolean` | `ehlo(String domain)` Issue the `EHLO` command.
    `protected void` | `finalize()` Stop the event dispatcher thread so the queue can be garbage collected.
    `protected void` | `finishData()` Terminate the sent data.
    `String` | `getAuthorizationId()` Gets the authorization ID to be used for authentication.
    `String` | `getExtensionParameter(String ext)` Return the parameter the server provided for the specified service extension, or null if the extension isn't supported.
    `int` | `getLastReturnCode()` Return the return code from the last response we got from the server.
    `String` | `getLastServerResponse()` Return the last response we got from the server.
    `String` | `getLocalHost()` Get the name of the local host, for use in the EHLO and HELO commands.
    `boolean` | `getNoopStrict()` Is the NOOP command required to return a response code of 250 to indicate success?
    `String` | `getNTLMDomain()` Gets the NTLM domain to be used for NTLM authentication.
    `boolean` | `getReportSuccess()` Should we report even successful sends by throwing an exception? If so, a `SendFailedException` will always be thrown and an `SMTPAddressSucceededException` will be included in the exception chain for each successful address, along with the usual `SMTPAddressFailedException` for each unsuccessful address.
    `boolean` | `getRequireStartTLS()` Should we require the STARTTLS command to secure the connection?
    `boolean` | `getSASLEnabled()` Is SASL authentication enabled?
    `String[]` | `getSASLMechanisms()` Get the list of SASL mechanisms to consider if SASL authentication is enabled.
    `String` | `getSASLRealm()` Gets the SASL realm to be used for DIGEST-MD5 authentication.
    `boolean` | `getStartTLS()` Should we use the STARTTLS command to secure the connection if the server supports it?
    `boolean` | `getUseCanonicalHostName()` Should SASL use the canonical host name?
    `boolean` | `getUseRset()` Should we use the RSET command instead of the NOOP command in the @{link #isConnected isConnected} method?
    `protected void` | `helo(String domain)` Issue the `HELO` command.
    `boolean` | `isConnected()` Check whether the transport is connected.
    `boolean` | `isSSL()` Is this Transport using SSL to connect to the server?
    `void` | `issueCommand(String cmd, int expect)` Send the command to the server.
    `protected void` | `mailFrom()` Issue the `MAIL FROM:` command to start sending a message.
    `protected void` | `notifyTransportListeners(int type, Address[] validSent, Address[] validUnsent, Address[] invalid, Message msg)` Notify all TransportListeners.
    `protected boolean` | `protocolConnect(String host, int port, String user, String passwd)` Performs the actual protocol-specific connection attempt.
    `protected void` | `rcptTo()` Sends each address to the SMTP host using the `RCPT TO:` command and copies the address either into the validSentAddr or invalidAddr arrays.
    `protected int` | `readServerResponse()` Reads server reponse returning the `returnCode` as the number.
    `boolean` | `sasllogin(String[] allowed, String realm, String authzid, String u, String p)` SASL-based login.
    `protected void` | `sendCommand(String cmd)` Sends command `cmd` to the server terminating it with `CRLF`.
    `void` | `sendMessage(Message message, Address[] addresses)` Send the Message to the specified list of addresses.
    `void` | `setAuthorizationID(String authzid)` Sets the authorization ID to be used for authentication.
    `void` | `setLocalHost(String localhost)` Set the name of the local host, for use in the EHLO and HELO commands.
    `void` | `setNoopStrict(boolean noopStrict)` Set whether the NOOP command is required to return a response code of 250 to indicate success.
    `void` | `setNTLMDomain(String ntlmDomain)` Sets the NTLM domain to be used for NTLM authentication.
    `void` | `setReportSuccess(boolean reportSuccess)` Set whether successful sends should be reported by throwing an exception.
    `void` | `setRequireStartTLS(boolean requireStartTLS)` Set whether the STARTTLS command should be required.
    `void` | `setSASLEnabled(boolean enableSASL)` Set whether SASL authentication is enabled.
    `void` | `setSASLMechanisms(String[] mechanisms)` Set the list of SASL mechanisms to consider if SASL authentication is enabled.
    `void` | `setSASLRealm(String saslRealm)` Sets the SASL realm to be used for DIGEST-MD5 authentication.
    `void` | `setStartTLS(boolean useStartTLS)` Set whether the STARTTLS command should be used.
    `void` | `setUseCanonicalHostName(boolean useCanonicalHostName)` Set whether SASL should use the canonical host name.
    `void` | `setUseRset(boolean useRset)` Set whether the RSET command should be used instead of the NOOP command in the @{link #isConnected isConnected} method.
    `protected int` | `simpleCommand(byte[] cmd)` Send the command to the server and return the response code from the server.
    `int` | `simpleCommand(String cmd)` Send the command to the server and return the response code from the server.
    `protected void` | `startTLS()` Issue the `STARTTLS` command and switch the socket to TLS mode if it succeeds.
    `protected boolean` | `supportsAuthentication(String auth)` Does the server we're connected to support the specified authentication mechanism? Uses the extension information returned by the server from the EHLO command.
    `boolean` | `supportsExtension(String ext)` Return true if the SMTP server supports the specified service extension.
    `protected static String` | `xtext(String s)` Convert a string to RFC 1891 xtext format.

    - ### Methods inherited from class javax.mail.Transport

      `addTransportListener, removeTransportListener, send, send, send, send`

    - ### Methods inherited from class javax.mail.Service

      `addConnectionListener, connect, connect, connect, connect, getURLName, notifyConnectionListeners, queueEvent, removeConnectionListener, setConnected, setURLName, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### SMTPTransport

          public SMTPTransport(Session session,
                       URLName urlname)

      Constructor that takes a Session object and a URLName that represents a specific SMTP server.
      Parameters:
        `session` - the Session
        `urlname` - the URLName of this transport

    - #### SMTPTransport

          protected SMTPTransport(Session session,
                       URLName urlname,
                       String name,
                       boolean isSSL)

      Constructor used by this class and by SMTPSSLTransport subclass.
      Parameters:
        `session` - the Session
        `urlname` - the URLName of this transport
        `name` - the protocol name of this transport
        `isSSL` - use SSL to connect?

  - ### Method Detail

    - #### getLocalHost

          public String getLocalHost()

      Get the name of the local host, for use in the EHLO and HELO commands. The property mail.smtp.localhost overrides mail.smtp.localaddress, which overrides what InetAddress would tell us.
      Returns:
        the local host name

    - #### setLocalHost

          public void setLocalHost(String localhost)

      Set the name of the local host, for use in the EHLO and HELO commands.
      Parameters:
        `localhost` - the local host name
      Since:
        JavaMail 1.3.1

    - #### connect

          public void connect(Socket socket)
                       throws MessagingException

      Start the SMTP protocol on the given socket, which was already connected by the caller. Useful for implementing the SMTP ATRN command (RFC 2645) where an existing connection is used when the server reverses roles and becomes the client.
      Parameters:
        `socket` - the already connected socket
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.3.3

    - #### getAuthorizationId

          public String getAuthorizationId()

      Gets the authorization ID to be used for authentication.
      Returns:
        the authorization ID to use for authentication.
      Since:
        JavaMail 1.4.4

    - #### setAuthorizationID

          public void setAuthorizationID(String authzid)

      Sets the authorization ID to be used for authentication.
      Parameters:
        `authzid` - the authorization ID to use for authentication.
      Since:
        JavaMail 1.4.4

    - #### getSASLEnabled

          public boolean getSASLEnabled()

      Is SASL authentication enabled?
      Returns:
        true if SASL authentication is enabled
      Since:
        JavaMail 1.4.4

    - #### setSASLEnabled

          public void setSASLEnabled(boolean enableSASL)

      Set whether SASL authentication is enabled.
      Parameters:
        `enableSASL` - should we enable SASL authentication?
      Since:
        JavaMail 1.4.4

    - #### getSASLRealm

          public String getSASLRealm()

      Gets the SASL realm to be used for DIGEST-MD5 authentication.
      Returns:
        the name of the realm to use for SASL authentication.
      Since:
        JavaMail 1.3.1

    - #### setSASLRealm

          public void setSASLRealm(String saslRealm)

      Sets the SASL realm to be used for DIGEST-MD5 authentication.
      Parameters:
        `saslRealm` - the name of the realm to use for SASL authentication.
      Since:
        JavaMail 1.3.1

    - #### getUseCanonicalHostName

          public boolean getUseCanonicalHostName()

      Should SASL use the canonical host name?
      Returns:
        true if SASL should use the canonical host name
      Since:
        JavaMail 1.5.2

    - #### setUseCanonicalHostName

          public void setUseCanonicalHostName(boolean useCanonicalHostName)

      Set whether SASL should use the canonical host name.
      Parameters:
        `useCanonicalHostName` - should SASL use the canonical host name?
      Since:
        JavaMail 1.5.2

    - #### getSASLMechanisms

          public String[] getSASLMechanisms()

      Get the list of SASL mechanisms to consider if SASL authentication is enabled. If the list is empty or null, all available SASL mechanisms are considered.
      Returns:
        the array of SASL mechanisms to consider
      Since:
        JavaMail 1.4.4

    - #### setSASLMechanisms

          public void setSASLMechanisms(String[] mechanisms)

      Set the list of SASL mechanisms to consider if SASL authentication is enabled. If the list is empty or null, all available SASL mechanisms are considered.
      Parameters:
        `mechanisms` - the array of SASL mechanisms to consider
      Since:
        JavaMail 1.4.4

    - #### getNTLMDomain

          public String getNTLMDomain()

      Gets the NTLM domain to be used for NTLM authentication.
      Returns:
        the name of the domain to use for NTLM authentication.
      Since:
        JavaMail 1.4.3

    - #### setNTLMDomain

          public void setNTLMDomain(String ntlmDomain)

      Sets the NTLM domain to be used for NTLM authentication.
      Parameters:
        `ntlmDomain` - the name of the domain to use for NTLM authentication.
      Since:
        JavaMail 1.4.3

    - #### getReportSuccess

          public boolean getReportSuccess()

      Should we report even successful sends by throwing an exception? If so, a `SendFailedException` will always be thrown and an `SMTPAddressSucceededException` will be included in the exception chain for each successful address, along with the usual `SMTPAddressFailedException` for each unsuccessful address.
      Returns:
        true if an exception will be thrown on successful sends.
      Since:
        JavaMail 1.3.2

    - #### setReportSuccess

          public void setReportSuccess(boolean reportSuccess)

      Set whether successful sends should be reported by throwing an exception.
      Parameters:
        `reportSuccess` - should we throw an exception on success?
      Since:
        JavaMail 1.3.2

    - #### getStartTLS

          public boolean getStartTLS()

      Should we use the STARTTLS command to secure the connection if the server supports it?
      Returns:
        true if the STARTTLS command will be used
      Since:
        JavaMail 1.3.2

    - #### setStartTLS

          public void setStartTLS(boolean useStartTLS)

      Set whether the STARTTLS command should be used.
      Parameters:
        `useStartTLS` - should we use the STARTTLS command?
      Since:
        JavaMail 1.3.2

    - #### getRequireStartTLS

          public boolean getRequireStartTLS()

      Should we require the STARTTLS command to secure the connection?
      Returns:
        true if the STARTTLS command will be required
      Since:
        JavaMail 1.4.2

    - #### setRequireStartTLS

          public void setRequireStartTLS(boolean requireStartTLS)

      Set whether the STARTTLS command should be required.
      Parameters:
        `requireStartTLS` - should we require the STARTTLS command?
      Since:
        JavaMail 1.4.2

    - #### isSSL

          public boolean isSSL()

      Is this Transport using SSL to connect to the server?
      Returns:
        true if using SSL
      Since:
        JavaMail 1.4.6

    - #### getUseRset

          public boolean getUseRset()

      Should we use the RSET command instead of the NOOP command in the @{link #isConnected isConnected} method?
      Returns:
        true if RSET will be used
      Since:
        JavaMail 1.4

    - #### setUseRset

          public void setUseRset(boolean useRset)

      Set whether the RSET command should be used instead of the NOOP command in the @{link #isConnected isConnected} method.
      Parameters:
        `useRset` - should we use the RSET command?
      Since:
        JavaMail 1.4

    - #### getNoopStrict

          public boolean getNoopStrict()

      Is the NOOP command required to return a response code of 250 to indicate success?
      Returns:
        true if NOOP must return 250
      Since:
        JavaMail 1.4.3

    - #### setNoopStrict

          public void setNoopStrict(boolean noopStrict)

      Set whether the NOOP command is required to return a response code of 250 to indicate success.
      Parameters:
        `noopStrict` - is NOOP required to return 250?
      Since:
        JavaMail 1.4.3

    - #### getLastServerResponse

          public String getLastServerResponse()

      Return the last response we got from the server. A failed send is often followed by an RSET command, but the response from the RSET command is not saved. Instead, this returns the response from the command before the RSET command.
      Returns:
        last response from server
      Since:
        JavaMail 1.3.2

    - #### getLastReturnCode

          public int getLastReturnCode()

      Return the return code from the last response we got from the server.
      Returns:
        return code from last response from server
      Since:
        JavaMail 1.4.1

    - #### protocolConnect

          protected boolean protocolConnect(String host,
                                int port,
                                String user,
                                String passwd)
                                     throws MessagingException

      Performs the actual protocol-specific connection attempt. Will attempt to connect to "localhost" if the host was null.

      Unless mail.smtp.ehlo is set to false, we'll try to identify ourselves using the ESMTP command EHLO. If mail.smtp.auth is set to true, we insist on having a username and password, and will try to authenticate ourselves if the server supports the AUTH extension (RFC 2554).

      Overrides:
        `protocolConnect` in class `Service`
      Parameters:
        `host` - the name of the host to connect to
        `port` - the port to use (-1 means use default port)
        `user` - the name of the user to login as
        `passwd` - the user's password
      Returns:
        true if connection successful, false if authentication failed
      Throws:
        `MessagingException` - for non-authentication failures

    - #### sasllogin

          public boolean sasllogin(String[] allowed,
                          String realm,
                          String authzid,
                          String u,
                          String p)
                            throws MessagingException

      SASL-based login.
      Parameters:
        `allowed` - the allowed SASL mechanisms
        `realm` - the SASL realm
        `authzid` - the authorization ID
        `u` - the user name for authentication
        `p` - the password for authentication
      Returns:
        true for success
      Throws:
        `MessagingException` - for failures

    - #### sendMessage

          public void sendMessage(Message message,
                         Address[] addresses)
                           throws MessagingException,
                                  SendFailedException

      Send the Message to the specified list of addresses.

      If all the `addresses` succeed the SMTP check using the `RCPT TO:` command, we attempt to send the message. A TransportEvent of type MESSAGE_DELIVERED is fired indicating the successful submission of a message to the SMTP host.

      If some of the `addresses` fail the SMTP check, and the `mail.smtp.sendpartial` property is not set, sending is aborted. The TransportEvent of type MESSAGE_NOT_DELIVERED is fired containing the valid and invalid addresses. The SendFailedException is also thrown.

      If some of the `addresses` fail the SMTP check, and the `mail.smtp.sendpartial` property is set to true, the message is sent. The TransportEvent of type MESSAGE_PARTIALLY_DELIVERED is fired containing the valid and invalid addresses. The SMTPSendFailedException is also thrown.

      MessagingException is thrown if the message can't write out an RFC822-compliant stream using its `writeTo` method.

      Specified by:
        `sendMessage` in class `Transport`
      Parameters:
        `message` - The MimeMessage to be sent
        `addresses` - List of addresses to send this message to
      Throws:
        `SMTPSendFailedException` - if the send failed because of an SMTP command error
        `SendFailedException` - if the send failed because of invalid addresses.
        `MessagingException` - if the connection is dead or not in the connected state or if the message is not a MimeMessage.
      See Also:
        `TransportEvent`

    - #### close

          public void close()
                     throws MessagingException

      Close the Transport and terminate the connection to the server.
      Overrides:
        `close` in class `Service`
      Throws:
        `MessagingException` - for errors while closing
      See Also:
        `ConnectionEvent`

    - #### isConnected

          public boolean isConnected()

      Check whether the transport is connected. Override superclass method, to actually ping our server connection.
      Overrides:
        `isConnected` in class `Service`
      Returns:
        true if the service is connected, false if it is not connected

    - #### notifyTransportListeners

          protected void notifyTransportListeners(int type,
                                      Address[] validSent,
                                      Address[] validUnsent,
                                      Address[] invalid,
                                      Message msg)

      Notify all TransportListeners. Keep track of whether notification has been done so as to only notify once per send.
      Overrides:
        `notifyTransportListeners` in class `Transport`
      Parameters:
        `type` - the TransportEvent type
        `validSent` - valid addresses to which message was sent
        `validUnsent` - valid addresses to which message was not sent
        `invalid` - the invalid addresses
        `msg` - the message
      Since:
        JavaMail 1.4.2

    - #### finalize

          protected void finalize()
                           throws Throwable

      Description copied from class: `Service`
      Stop the event dispatcher thread so the queue can be garbage collected.
      Overrides:
        `finalize` in class `Service`
      Throws:
        `Throwable`

    - #### helo

          protected void helo(String domain)
                       throws MessagingException

      Issue the `HELO` command.
      Parameters:
        `domain` - our domain
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### ehlo

          protected boolean ehlo(String domain)
                          throws MessagingException

      Issue the `EHLO` command. Collect the returned list of service extensions.
      Parameters:
        `domain` - our domain
      Returns:
        true if command succeeds
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### mailFrom

          protected void mailFrom()
                           throws MessagingException

      Issue the `MAIL FROM:` command to start sending a message.

      Gets the sender's address in the following order:

      1. SMTPMessage.getEnvelopeFrom()
      2. mail.smtp.from property
      3. From: header in the message
      4. System username using the InternetAddress.getLocalAddress() method
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### rcptTo

          protected void rcptTo()
                         throws MessagingException

      Sends each address to the SMTP host using the `RCPT TO:` command and copies the address either into the validSentAddr or invalidAddr arrays. Sets the `sendFailed` flag to true if any addresses failed.
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### data

          protected OutputStream data()
                               throws MessagingException

      Send the `DATA` command to the SMTP host and return an OutputStream to which the data is to be written.
      Returns:
        the stream to write to
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### finishData

          protected void finishData()
                             throws IOException,
                                    MessagingException

      Terminate the sent data.
      Throws:
        `IOException` - for I/O errors
        `MessagingException` - for other failures
      Since:
        JavaMail 1.4.1

    - #### startTLS

          protected void startTLS()
                           throws MessagingException

      Issue the `STARTTLS` command and switch the socket to TLS mode if it succeeds.
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### issueCommand

          public void issueCommand(String cmd,
                          int expect)
                            throws MessagingException

      Send the command to the server. If the expected response code is not received, throw a MessagingException.
      Parameters:
        `cmd` - the command to send
        `expect` - the expected response code (-1 means don't care)
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### simpleCommand

          public int simpleCommand(String cmd)
                            throws MessagingException

      Send the command to the server and return the response code from the server.
      Parameters:
        `cmd` - the command
      Returns:
        the response code
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### simpleCommand

          protected int simpleCommand(byte[] cmd)
                               throws MessagingException

      Send the command to the server and return the response code from the server.
      Parameters:
        `cmd` - the command
      Returns:
        the response code
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### sendCommand

          protected void sendCommand(String cmd)
                              throws MessagingException

      Sends command `cmd` to the server terminating it with `CRLF`.
      Parameters:
        `cmd` - the command
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### readServerResponse

          protected int readServerResponse()
                                    throws MessagingException

      Reads server reponse returning the `returnCode` as the number. Returns -1 on failure. Sets `lastServerResponse` and `lastReturnCode`.
      Returns:
        server response code
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4.1

    - #### checkConnected

          protected void checkConnected()

      Check if we're in the connected state. Don't bother checking whether the server is still alive, that will be detected later.
      Throws:
        `IllegalStateException` - if not connected
      Since:
        JavaMail 1.4.1

    - #### supportsExtension

          public boolean supportsExtension(String ext)

      Return true if the SMTP server supports the specified service extension. Extensions are reported as results of the EHLO command when connecting to the server. See RFC 1869 and other RFCs that define specific extensions.
      Parameters:
        `ext` - the service extension name
      Returns:
        true if the extension is supported
      Since:
        JavaMail 1.3.2

    - #### getExtensionParameter

          public String getExtensionParameter(String ext)

      Return the parameter the server provided for the specified service extension, or null if the extension isn't supported.
      Parameters:
        `ext` - the service extension name
      Returns:
        the extension parameter
      Since:
        JavaMail 1.3.2

    - #### supportsAuthentication

          protected boolean supportsAuthentication(String auth)

      Does the server we're connected to support the specified authentication mechanism? Uses the extension information returned by the server from the EHLO command.
      Parameters:
        `auth` - the authentication mechanism
      Returns:
        true if the authentication mechanism is supported
      Since:
        JavaMail 1.4.1

    - #### xtext

          protected static String xtext(String s)

      Convert a string to RFC 1891 xtext format.

               xtext = *( xchar / hexchar )

               xchar = any ASCII CHAR between "!" (33) and "~" (126) inclusive,
                    except for "+" and "=".

           ; "hexchar"s are intended to encode octets that cannot appear
           ; as ASCII characters within an esmtp-value.

               hexchar = ASCII "+" immediately followed by two upper case
                    hexadecimal digits

      Parameters:
        `s` - the string to convert
      Returns:
        the xtext format string
      Since:
        JavaMail 1.4.1

Copyright © 2016 Oracle. All rights reserved.