## 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();
            }

See Also:
  `ConnectionEvent`, `TransportEvent`

Field Summary

Fields inherited from class javax.mail.Service
`debug, session, url`

Constructor Summary
`` `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, java.lang.String name, int defaultPort, boolean isSSL)` Constructor used by this class and by SMTPSSLTransport subclass.

Method Summary
`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(java.net.Socket socket)` Start the SMTP protocol on the given socket, which was already connected by the caller.
`protected java.io.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(java.lang.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.
`java.lang.String` `getExtensionParameter(java.lang.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.
`java.lang.String` `getLastServerResponse()` Return the last response we got from the server.
`java.lang.String` `getLocalHost()` Get the name of the local host, for use in the EHLO and HELO commands.
`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.
`java.lang.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` `getUseRset()` Should we use the RSET command instead of the NOOP command in the @{link #isConnected isConnected} method?
`protected void` `helo(java.lang.String domain)` Issue the `HELO` command.
`boolean` `isConnected()` Check whether the transport is connected.
`void` `issueCommand(java.lang.String cmd, int expect)` Send the command to the server.
`protected void` `mailFrom()` Issue the `MAIL FROM:` command to start sending a message.
`protected boolean` `protocolConnect(java.lang.String host, int port, java.lang.String user, java.lang.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.
`protected void` `sendCommand(java.lang.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` `setLocalHost(java.lang.String localhost)` Set the name of the local host, for use in the EHLO and HELO commands.
`void` `setReportSuccess(boolean reportSuccess)` Set whether successful sends should be reported by throwing an exception.
`void` `setSASLRealm(java.lang.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` `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(java.lang.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(java.lang.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(java.lang.String ext)` Return true if the SMTP server supports the specified service extension.
`protected static java.lang.String` `xtext(java.lang.String s)` Convert a string to RFC 1891 xtext format.

Methods inherited from class javax.mail.Transport
`addTransportListener, notifyTransportListeners, removeTransportListener, 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.

### SMTPTransport

    protected SMTPTransport(Session session,
                            URLName urlname,
                            java.lang.String name,
                            int defaultPort,
                            boolean isSSL)

  Constructor used by this class and by SMTPSSLTransport subclass.

Method Detail

### getLocalHost

    public java.lang.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.

### setLocalHost

    public void setLocalHost(java.lang.String localhost)

  Set the name of the local host, for use in the EHLO and HELO commands.

  Since:
    JavaMail 1.3.1

### connect

    public void connect(java.net.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.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.3.3

### getSASLRealm

    public java.lang.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(java.lang.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

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

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

### getLastServerResponse

    public java.lang.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(java.lang.String host,
                                      int port,
                                      java.lang.String user,
                                      java.lang.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

### 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.stmp.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.stmp.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

### finalize

    protected void finalize()
                     throws java.lang.Throwable

  Description copied from class: `Service`
  Stop the event dispatcher thread so the queue can be garbage collected.

  Overrides:
    `finalize` in class `Service`
  Throws:
    `java.lang.Throwable`

### helo

    protected void helo(java.lang.String domain)
                 throws MessagingException

  Issue the `HELO` command.

  Parameters:
    `domain` - our domain
  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4.1

### ehlo

    protected boolean ehlo(java.lang.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`
  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`
  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`
  Since:
    JavaMail 1.4.1

### data

    protected java.io.OutputStream data()
                                 throws MessagingException

  Send the `DATA` command to the SMTP host and return an OutputStream to which the data is to be written.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4.1

### finishData

    protected void finishData()
                       throws java.io.IOException,
                              MessagingException

  Terminate the sent data.

  Throws:
    `java.io.IOException`
    `MessagingException`
  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`
  Since:
    JavaMail 1.4.1

### issueCommand

    public void issueCommand(java.lang.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
  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4.1

### simpleCommand

    public int simpleCommand(java.lang.String cmd)
                      throws MessagingException

  Send the command to the server and return the response code from the server.

  Throws:
    `MessagingException`
  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.

  Throws:
    `MessagingException`
  Since:
    JavaMail 1.4.1

### sendCommand

    protected void sendCommand(java.lang.String cmd)
                        throws MessagingException

  Sends command `cmd` to the server terminating it with `CRLF`.

  Throws:
    `MessagingException`
  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`
  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:
    `java.lang.IllegalStateException` - if not connected
  Since:
    JavaMail 1.4.1

### supportsExtension

    public boolean supportsExtension(java.lang.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 java.lang.String getExtensionParameter(java.lang.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(java.lang.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 java.lang.String xtext(java.lang.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

  Since:
    JavaMail 1.4.1