SMTP (Apache Commons Net 3.4 API)

org.apache.commons.net.smtp

## Class SMTP

- java.lang.Object
- - org.apache.commons.net.SocketClient
  - - org.apache.commons.net.smtp.SMTP

- Direct Known Subclasses:
    SMTPClient

      public class SMTP
      extends SocketClient

  SMTP provides the basic the functionality necessary to implement your own SMTP client. To derive the full benefits of the SMTP class requires some knowledge of the FTP protocol defined in RFC 821. However, there is no reason why you should have to use the SMTP class. The `SMTPClient` class, derived from SMTP, implements all the functionality required of an SMTP client. The SMTP class is made public to provide access to various SMTP constants and to make it easier for adventurous programmers (or those with special needs) to interact with the SMTP protocol and implement their own clients. A set of methods with names corresponding to the SMTP command names are provided to facilitate this interaction.

  You should keep in mind that the SMTP server may choose to prematurely close a connection for various reasons. The SMTP class will detect a premature SMTP server connection closing when it receives a `SMTPReply.SERVICE_NOT_AVAILABLE` response to a command. When that occurs, the SMTP class method encountering that reply will throw an `SMTPConnectionClosedException` . `SMTPConectionClosedException` is a subclass of `IOException` and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear before the more general `IOException` catch block. When you encounter an `SMTPConnectionClosedException` , you must disconnect the connection with `disconnect()` to properly clean up the system resources used by SMTP. Before disconnecting, you may check the last reply code and text with `getReplyCode` , `getReplyString` , and `getReplyStrings`.

  Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a `MalformedServerReplyException` , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as lenient as possible.

  See Also:
    `SMTPClient`, `SMTPConnectionClosedException`, `MalformedServerReplyException`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ProtocolCommandSupport` | `_commandSupport_` A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.
    `static int` | `DEFAULT_PORT` The default SMTP port (25).
    `protected String` | `encoding` The encoding to use (user-settable).

    - ### Fields inherited from class org.apache.commons.net.SocketClient

      `_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SMTP()` The default SMTP constructor.
    `SMTP(String encoding)` Overloaded constructor where the user may specify a default encoding.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `_connectAction_()` Initiates control connections and gets initial reply.
    `int` | `data()` A convenience method to send the SMTP DATA command to the server, receive the reply, and return the reply code.
    `void` | `disconnect()` Closes the connection to the SMTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector.
    `int` | `expn(String name)` A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.
    `protected ProtocolCommandSupport` | `getCommandSupport()` Provide command support to super-class
    `int` | `getReply()` Fetches a reply from the SMTP server and returns the integer reply code.
    `int` | `getReplyCode()` Returns the integer value of the reply code of the last SMTP reply.
    `String` | `getReplyString()` Returns the entire text of the last SMTP server response exactly as it was received, including all end of line markers in NETASCII format.
    `String[]` | `getReplyStrings()` Returns the lines of text from the last SMTP server response as an array of strings, one entry per line.
    `int` | `helo(String hostname)` A convenience method to send the SMTP HELO command to the server, receive the reply, and return the reply code.
    `int` | `help()` A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.
    `int` | `help(String command)` A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.
    `int` | `mail(String reversePath)` A convenience method to send the SMTP MAIL command to the server, receive the reply, and return the reply code.
    `int` | `noop()` A convenience method to send the SMTP NOOP command to the server, receive the reply, and return the reply code.
    `int` | `quit()` A convenience method to send the SMTP QUIT command to the server, receive the reply, and return the reply code.
    `int` | `rcpt(String forwardPath)` A convenience method to send the SMTP RCPT command to the server, receive the reply, and return the reply code.
    `void` | `removeProtocolCommandistener(ProtocolCommandListener listener)` Removes a ProtocolCommandListener.
    `int` | `rset()` A convenience method to send the SMTP RSET command to the server, receive the reply, and return the reply code.
    `int` | `saml(String reversePath)` A convenience method to send the SMTP SAML command to the server, receive the reply, and return the reply code.
    `int` | `send(String reversePath)` A convenience method to send the SMTP SEND command to the server, receive the reply, and return the reply code.
    `int` | `sendCommand(int command)` Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code.
    `int` | `sendCommand(int command, String args)` Sends an SMTP command to the server, waits for a reply and returns the numerical response code.
    `int` | `sendCommand(String command)` Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code.
    `int` | `sendCommand(String command, String args)` Sends an SMTP command to the server, waits for a reply and returns the numerical response code.
    `int` | `soml(String reversePath)` A convenience method to send the SMTP SOML command to the server, receive the reply, and return the reply code.
    `int` | `turn()` A convenience method to send the SMTP TURN command to the server, receive the reply, and return the reply code.
    `int` | `vrfy(String user)` A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.

    - ### Methods inherited from class org.apache.commons.net.SocketClient

      `addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCharsetName, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote`

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

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

- - ### Field Detail

    - #### DEFAULT_PORT

          public static final int DEFAULT_PORT

      The default SMTP port (25).
      See Also:
        Constant Field Values

    - #### encoding

          protected final String encoding

      The encoding to use (user-settable).
      Since:
        3.1 (changed from private to protected)

    - #### _commandSupport_

          protected ProtocolCommandSupport _commandSupport_

      A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.

  - ### Constructor Detail

    - #### SMTP

          public SMTP()

      The default SMTP constructor. Sets the default port to `DEFAULT_PORT` and initializes internal data structures for saving SMTP reply information.

    - #### SMTP

          public SMTP(String encoding)

      Overloaded constructor where the user may specify a default encoding.
      Parameters:
        `encoding` - the encoing to use
      Since:
        2.0

  - ### Method Detail

    - #### _connectAction_

          protected void _connectAction_()
                                  throws IOException

      Initiates control connections and gets initial reply.
      Overrides:
        `_connectAction_` in class `SocketClient`
      Throws:
        `IOException` - (SocketException) if a problem occurs with the socket

    - #### disconnect

          public void disconnect()
                          throws IOException

      Closes the connection to the SMTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector. The reply text and code information from the last command is voided so that the memory it used may be reclaimed.

      Overrides:
        `disconnect` in class `SocketClient`
      Throws:
        `IOException` - If an error occurs while disconnecting.

    - #### sendCommand

          public int sendCommand(String command,
                        String args)
                          throws IOException

      Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling `getReplyString` or `getReplyStrings` .

      Parameters:
        `command` - The text representation of the SMTP command to send.
        `args` - The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
      Returns:
        The integer value of the SMTP reply code returned by the server in response to the command.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### sendCommand

          public int sendCommand(int command,
                        String args)
                          throws IOException

      Sends an SMTP command to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling `getReplyString` or `getReplyStrings` .

      Parameters:
        `command` - The SMTPCommand constant corresponding to the SMTP command to send.
        `args` - The arguments to the SMTP command. If this parameter is set to null, then the command is sent with no argument.
      Returns:
        The integer value of the SMTP reply code returned by the server in response to the command.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### sendCommand

          public int sendCommand(String command)
                          throws IOException

      Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling `getReplyString` or `getReplyStrings` .

      Parameters:
        `command` - The text representation of the SMTP command to send.
      Returns:
        The integer value of the SMTP reply code returned by the server in response to the command.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### sendCommand

          public int sendCommand(int command)
                          throws IOException

      Sends an SMTP command with no arguments to the server, waits for a reply and returns the numerical response code. After invocation, for more detailed information, the actual reply text can be accessed by calling `getReplyString` or `getReplyStrings` .

      Parameters:
        `command` - The SMTPCommand constant corresponding to the SMTP command to send.
      Returns:
        The integer value of the SMTP reply code returned by the server in response to the command.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### getReplyCode

          public int getReplyCode()

      Returns the integer value of the reply code of the last SMTP reply. You will usually only use this method after you connect to the SMTP server to check that the connection was successful since `connect` is of type void.

      Returns:
        The integer value of the reply code of the last SMTP reply.

    - #### getReply

          public int getReply()
                       throws IOException

      Fetches a reply from the SMTP server and returns the integer reply code. After calling this method, the actual reply text can be accessed from either calling `getReplyString` or `getReplyStrings` . Only use this method if you are implementing your own SMTP client or if you need to fetch a secondary response from the SMTP server.

      Returns:
        The integer value of the reply code of the fetched SMTP reply.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while receiving the server reply.

    - #### getReplyStrings

          public String[] getReplyStrings()

      Returns the lines of text from the last SMTP server response as an array of strings, one entry per line. The end of line markers of each are stripped from each line.

      Returns:
        The lines of text from the last SMTP response as an array.

    - #### getReplyString

          public String getReplyString()

      Returns the entire text of the last SMTP server response exactly as it was received, including all end of line markers in NETASCII format.

      Returns:
        The entire text from the last SMTP response as a String.

    - #### helo

          public int helo(String hostname)
                   throws IOException

      A convenience method to send the SMTP HELO command to the server, receive the reply, and return the reply code.

      Parameters:
        `hostname` - The hostname of the sender.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### mail

          public int mail(String reversePath)
                   throws IOException

      A convenience method to send the SMTP MAIL command to the server, receive the reply, and return the reply code.

      Parameters:
        `reversePath` - The reverese path.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### rcpt

          public int rcpt(String forwardPath)
                   throws IOException

      A convenience method to send the SMTP RCPT command to the server, receive the reply, and return the reply code.

      Parameters:
        `forwardPath` - The forward path.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### data

          public int data()
                   throws IOException

      A convenience method to send the SMTP DATA command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### send

          public int send(String reversePath)
                   throws IOException

      A convenience method to send the SMTP SEND command to the server, receive the reply, and return the reply code.

      Parameters:
        `reversePath` - The reverese path.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### soml

          public int soml(String reversePath)
                   throws IOException

      A convenience method to send the SMTP SOML command to the server, receive the reply, and return the reply code.

      Parameters:
        `reversePath` - The reverese path.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### saml

          public int saml(String reversePath)
                   throws IOException

      A convenience method to send the SMTP SAML command to the server, receive the reply, and return the reply code.

      Parameters:
        `reversePath` - The reverese path.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### rset

          public int rset()
                   throws IOException

      A convenience method to send the SMTP RSET command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### vrfy

          public int vrfy(String user)
                   throws IOException

      A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.

      Parameters:
        `user` - The user address to verify.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### expn

          public int expn(String name)
                   throws IOException

      A convenience method to send the SMTP VRFY command to the server, receive the reply, and return the reply code.

      Parameters:
        `name` - The name to expand.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### help

          public int help()
                   throws IOException

      A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### help

          public int help(String command)
                   throws IOException

      A convenience method to send the SMTP HELP command to the server, receive the reply, and return the reply code.

      Parameters:
        `command` - The command name on which to request help.
      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### noop

          public int noop()
                   throws IOException

      A convenience method to send the SMTP NOOP command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### turn

          public int turn()
                   throws IOException

      A convenience method to send the SMTP TURN command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### quit

          public int quit()
                   throws IOException

      A convenience method to send the SMTP QUIT command to the server, receive the reply, and return the reply code.

      Returns:
        The reply code received from the server.
      Throws:
        `SMTPConnectionClosedException` - If the SMTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send SMTP reply code 421. This exception may be caught either as an IOException or independently as itself.
        `IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### removeProtocolCommandistener

          public void removeProtocolCommandistener(ProtocolCommandListener listener)

      Removes a ProtocolCommandListener. Delegates this incorrectly named method - removeProtocolCommandistener (note the missing "L")- to the correct method `SocketClient.removeProtocolCommandListener(org.apache.commons.net.ProtocolCommandListener)`
      Parameters:
        `listener` - The ProtocolCommandListener to remove

    - #### getCommandSupport

          protected ProtocolCommandSupport getCommandSupport()

      Provide command support to super-class
      Overrides:
        `getCommandSupport` in class `SocketClient`
      Returns:
        the CommandSupport instance, may be `null`

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.