AuthenticatingSMTPClient
Date: 2016-06-23

org.apache.commons.net.smtp

## Class AuthenticatingSMTPClient

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

-     public class AuthenticatingSMTPClient
      extends SMTPSClient

  An SMTP Client class with authentication support (RFC4954).
  Since:
    3.0
  See Also:
    `SMTPClient`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AuthenticatingSMTPClient.AUTH_METHOD` The enumeration of currently-supported authentication methods.

  - ### Field Summary

    - ### Fields inherited from class org.apache.commons.net.smtp.SMTP

      `_commandSupport_, DEFAULT_PORT, encoding`

    - ### 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
    `AuthenticatingSMTPClient()` The default AuthenticatingSMTPClient constructor.
    `AuthenticatingSMTPClient(boolean implicit, javax.net.ssl.SSLContext ctx)` Overloaded constructor that takes the implicit argument, and using `SMTPSClient.DEFAULT_PROTOCOL` i.e.
    `AuthenticatingSMTPClient(java.lang.String protocol)` Overloaded constructor that takes a protocol specification
    `AuthenticatingSMTPClient(java.lang.String proto, boolean implicit)` Overloaded constructor that takes a protocol specification and the implicit argument
    `AuthenticatingSMTPClient(java.lang.String proto, boolean implicit, java.lang.String encoding)` Overloaded constructor that takes the protocol specification, the implicit argument and encoding
    `AuthenticatingSMTPClient(java.lang.String protocol, java.lang.String encoding)` Overloaded constructor that takes a protocol specification and encoding

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `auth(AuthenticatingSMTPClient.AUTH_METHOD method, java.lang.String username, java.lang.String password)` Authenticate to the SMTP server by sending the AUTH command with the selected mechanism, using the given username and the given password.
    `int` | `ehlo(java.lang.String hostname)` A convenience method to send the ESMTP EHLO command to the server, receive the reply, and return the reply code.
    `boolean` | `elogin()` Login to the ESMTP server by sending the EHLO command with the client hostname as an argument.
    `boolean` | `elogin(java.lang.String hostname)` Login to the ESMTP server by sending the EHLO command with the given hostname as an argument.
    `int[]` | `getEnhancedReplyCode()` Returns the integer values of the enhanced reply code of the last SMTP reply.

    - ### Methods inherited from class org.apache.commons.net.smtp.SMTPSClient

      `_connectAction_, execTLS, getEnabledCipherSuites, getEnabledProtocols, getHostnameVerifier, getKeyManager, getTrustManager, isEndpointCheckingEnabled, setEnabledCipherSuites, setEnabledProtocols, setEndpointCheckingEnabled, setHostnameVerifier, setKeyManager, setTrustManager`

    - ### Methods inherited from class org.apache.commons.net.smtp.SMTPClient

      `addRecipient, addRecipient, completePendingCommand, listHelp, listHelp, login, login, logout, reset, sendMessageData, sendNoOp, sendShortMessageData, sendSimpleMessage, sendSimpleMessage, setSender, setSender, verify`

    - ### Methods inherited from class org.apache.commons.net.smtp.SMTP

      `data, disconnect, expn, getCommandSupport, getReply, getReplyCode, getReplyString, getReplyStrings, helo, help, help, mail, noop, quit, rcpt, removeProtocolCommandistener, rset, saml, send, sendCommand, sendCommand, sendCommand, sendCommand, soml, turn, vrfy`

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

- - ### Constructor Detail

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient()

      The default AuthenticatingSMTPClient constructor. Creates a new Authenticating SMTP Client.

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient(java.lang.String protocol)

      Overloaded constructor that takes a protocol specification
      Parameters:
        `protocol` - The protocol to use

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient(java.lang.String proto,
                                  boolean implicit)

      Overloaded constructor that takes a protocol specification and the implicit argument
      Parameters:
        `proto` - the protocol.
        `implicit` - The security mode, `true` for implicit, `false` for explicit
      Since:
        3.3

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient(java.lang.String proto,
                                  boolean implicit,
                                  java.lang.String encoding)

      Overloaded constructor that takes the protocol specification, the implicit argument and encoding
      Parameters:
        `proto` - the protocol.
        `implicit` - The security mode, `true` for implicit, `false` for explicit
        `encoding` - the encoding
      Since:
        3.3

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient(boolean implicit,
                                  javax.net.ssl.SSLContext ctx)

      Overloaded constructor that takes the implicit argument, and using `SMTPSClient.DEFAULT_PROTOCOL` i.e. TLS
      Parameters:
        `implicit` - The security mode, `true` for implicit, `false` for explicit
        `ctx` - A pre-configured SSL Context.
      Since:
        3.3

    - #### AuthenticatingSMTPClient

          public AuthenticatingSMTPClient(java.lang.String protocol,
                                  java.lang.String encoding)

      Overloaded constructor that takes a protocol specification and encoding
      Parameters:
        `protocol` - The protocol to use
        `encoding` - The encoding to use
      Since:
        3.3

  - ### Method Detail

    - #### ehlo

          public int ehlo(java.lang.String hostname)
                   throws java.io.IOException

      A convenience method to send the ESMTP EHLO 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.
        `java.io.IOException` - If an I/O error occurs while either sending the command or receiving the server reply.

    - #### elogin

          public boolean elogin(java.lang.String hostname)
                         throws java.io.IOException

      Login to the ESMTP server by sending the EHLO command with the given hostname as an argument. Before performing any mail commands, you must first login.

      Parameters:
        `hostname` - The hostname with which to greet the SMTP server.
      Returns:
        True if successfully completed, false if not.
      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.
        `java.io.IOException` - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

    - #### elogin

          public boolean elogin()
                         throws java.io.IOException

      Login to the ESMTP server by sending the EHLO command with the client hostname as an argument. Before performing any mail commands, you must first login.

      Returns:
        True if successfully completed, false if not.
      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.
        `java.io.IOException` - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

    - #### getEnhancedReplyCode

          public int[] getEnhancedReplyCode()

      Returns the integer values of the enhanced reply code of the last SMTP reply.
      Returns:
        The integer values of the enhanced reply code of the last SMTP reply. First digit is in the first array element.

    - #### auth

          public boolean auth(AuthenticatingSMTPClient.AUTH_METHOD method,
                     java.lang.String username,
                     java.lang.String password)
                       throws java.io.IOException,
                              java.security.NoSuchAlgorithmException,
                              java.security.InvalidKeyException,
                              java.security.spec.InvalidKeySpecException

      Authenticate to the SMTP server by sending the AUTH command with the selected mechanism, using the given username and the given password.
      Parameters:
        `method` - the method to use, one of the `AuthenticatingSMTPClient.AUTH_METHOD` enum values
        `username` - the user name. If the method is XOAUTH, then this is used as the plain text oauth protocol parameter string which is Base64-encoded for transmission.
        `password` - the password for the username. Ignored for XOAUTH.
      Returns:
        True if successfully completed, false if not.
      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.
        `java.io.IOException` - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
        `java.security.NoSuchAlgorithmException` - If the CRAM hash algorithm cannot be instantiated by the Java runtime system.
        `java.security.InvalidKeyException` - If the CRAM hash algorithm failed to use the given password.
        `java.security.spec.InvalidKeySpecException` - If the CRAM hash algorithm failed to use the given password.