SmtpSession (NioSmtpClient 0.0.1-SNAPSHOT API)

java.lang.Object
- com.hubspot.smtp.client.SmtpSession

```
public class SmtpSession
extends Object
```
An open connection to an SMTP server which can be used to send messages and other commands.
SmtpSession instances can be created with SmtpSessionFactory.connect(SmtpSessionConfig).
This class is thread-safe.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CompletableFuture<SmtpClientResponse>`	`authLogin(String username, String password)` Authenticates with the remote server using the LOGIN mechanism.
`CompletableFuture<SmtpClientResponse>`	`authPlain(String username, String password)` Authenticates with the remote server using the PLAIN mechanism.
`CompletableFuture<SmtpClientResponse>`	`authXoauth2(String username, String accessToken)` Authenticates with the remote server using the XOAUTH2 mechanism.
`CompletableFuture<Void>`	`close()` Closes this session.
`CompletableFuture<Void>`	`getCloseFuture()` Returns a `CompletableFuture` that will be completed when this session is closed.
`String`	`getConnectionId()` Returns the `connectionId` defined by the `SmtpSessionConfig` used when connecting to this server.
`EhloResponse`	`getEhloResponse()` Returns an `EhloResponse` representing the capabilities of the connection server.
`Optional<SSLSession>`	`getSSLSession()` Returns the `SSLSession` used by the current session, or `Optional.empty()` if the session is not using TLS.
`boolean`	`isEncrypted()` Returns true if TLS is active on the session.
`CompletableFuture<SmtpClientResponse>`	`send(MessageContent content)` Sends message content to the remote server and waits for a response.
`CompletableFuture<SmtpClientResponse>`	`send(io.netty.handler.codec.smtp.SmtpRequest request)` Sends a command to the remote server and waits for a response.
`CompletableFuture<SmtpClientResponse>`	`send(String from, Collection<String> recipients, MessageContent content)` Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server.
`CompletableFuture<SmtpClientResponse>`	`send(String from, Collection<String> recipients, MessageContent content, SendInterceptor sendInterceptor)` Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server.
`CompletableFuture<SmtpClientResponse>`	`send(String from, String to, MessageContent content)` Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server.
`CompletableFuture<SmtpClientResponse>`	`send(String from, String to, MessageContent content, SendInterceptor sendInterceptor)` Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server.
`CompletableFuture<SmtpClientResponse>`	`sendChunk(io.netty.buffer.ByteBuf data, boolean isLast)` Sends binary message content to the remote server and waits for a response.
`CompletableFuture<SmtpClientResponse>`	`sendPipelined(MessageContent content, io.netty.handler.codec.smtp.SmtpRequest... requests)` Sends a series of commands to the server without waiting for a response.
`CompletableFuture<SmtpClientResponse>`	`sendPipelined(io.netty.handler.codec.smtp.SmtpRequest... requests)` Sends a series of commands to the server without waiting for a response.
`CompletableFuture<SmtpClientResponse>`	`startTls()` Sends the STARTTLS command and tries to use TLS for this session.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getConnectionId
```
public String getConnectionId()
```
    Returns the connectionId defined by the SmtpSessionConfig used when connecting to this server.
  - getCloseFuture
```
public CompletableFuture<Void> getCloseFuture()
```
    Returns a CompletableFuture that will be completed when this session is closed.
  - getEhloResponse
```
public EhloResponse getEhloResponse()
```
    Returns an EhloResponse representing the capabilities of the connection server.
    If the EHLO command has not been sent, or the response could not be parsed, this method will return an empty EhloResponse that assumes no extended SMTP features are available.
  - close
```
public CompletableFuture<Void> close()
```
    Closes this session.
    
    Returns:
    
    a CompletableFuture that will be completed when the session is closed.
  - startTls
```
public CompletableFuture<SmtpClientResponse> startTls()
```
    Sends the STARTTLS command and tries to use TLS for this session.
    If the server returns an error response (with code >= 400), this method will return a CompletableFuture<SmtpClientResponse> with that error response and TLS will not be active.
    If the TLS handshake fails, this method will return a CompletableFuture<SmtpClientResponse> that contains the exception thrown by the handshake process.
    Once the TLS handshake has completed, the EHLO command will be sent again in accordance with the spec. The EHLO response will be parsed and available from getEhloResponse().
    
    Returns:
    
    a future containing the response to the STARTTLS command
    
    Throws:
    
    IllegalStateException - if TLS is already active
  - isEncrypted
```
public boolean isEncrypted()
```
    Returns true if TLS is active on the session.
  - getSSLSession
```
public Optional<SSLSession> getSSLSession()
```
    Returns the SSLSession used by the current session, or Optional.empty() if the session is not using TLS.
  - send
```
public CompletableFuture<SmtpClientResponse> send(String from,
                                                  String to,
                                                  MessageContent content)
```
    Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server. This method behaves as send(String, Collection, MessageContent, SendInterceptor) but only specifies one recipient and does not use a SendInterceptor.
  - send
```
public CompletableFuture<SmtpClientResponse> send(String from,
                                                  String to,
                                                  MessageContent content,
                                                  SendInterceptor sendInterceptor)
```
    Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server. This method behaves as send(String, Collection, MessageContent, SendInterceptor) but only specifies one recipient.
  - send
```
public CompletableFuture<SmtpClientResponse> send(String from,
                                                  Collection<String> recipients,
                                                  MessageContent content)
```
    Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server. This method behaves as send(String, Collection, MessageContent, SendInterceptor) but does not use a SendInterceptor.
  - send
```
public CompletableFuture<SmtpClientResponse> send(String from,
                                                  Collection<String> recipients,
                                                  MessageContent content,
                                                  SendInterceptor sendInterceptor)
```
    Sends an email as efficiently as possible, using the extended SMTP features supported by the remote server.
    This method sends multiple commands to the remote server, and may use pipelining and other features if supported. If any command receives an error response (i.e. with code >= 400), the sequence of commands is aborted.
    Because this method adapts to the capabilities of the server, it may send different sequences of commands for the same inputs. For example, communication with a server without extended SMTP support might look as follows:
```
  CLIENT: MAIL FROM:<from@example.com>
  SERVER: 250 OK
  CLIENT: RCPT TO:<to@example.com>
  SERVER: 250 OK
  CLIENT: DATA
  SERVER: 354 Start mail input; end with <CRLF>.
  CLIENT: <message data>
```
    Communication with a modern server that supports pipelining and chunking might look different:
```
  CLIENT: MAIL FROM:<from@example.com>
  CLIENT: RCPT TO:<to@example.com>
  CLIENT: BDAT 7287 LAST
  CLIENT: <binary message data>
  SERVER: 250 OK
  SERVER: 250 OK
  SERVER: 250 OK
```
    This command assumes the EHLO command has been sent and its result has been parsed.
    Dot-stuffing will be performed automatically unless SMTP chunking (which does not require dot-stuffing) is available.
    Parameters:
    
    from - the sender of the message, surrounded by < and >, e.g. "<alice@example.com>"
    
    recipients - a list of the intended recipients, each surrounded by < and >, e.g. ["<bob@example.com>", "<carol@example.com>"]
    
    content - a MessageContent with the contents of the message
    
    sendInterceptor - a SendInterceptor which will be called before commands and data are sent
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain each of the responses received from the remote server, or an exception if the send failed unexpectedly.
    
    Throws:
    
    NullPointerException - if any of the arguments are null
    
    IllegalArgumentException - if recipients is empty
    
    MessageTooLargeException - if the EHLO response indicated a maximum message size that would be exceeded by content. Note if MessageContent.size() is not specified this check is not performed.
  - send
```
public CompletableFuture<SmtpClientResponse> send(io.netty.handler.codec.smtp.SmtpRequest request)
```
    Sends a command to the remote server and waits for a response.
    If the command is EHLO, the server's response will be parsed and available from getEhloResponse().
    
    Parameters:
    
    request - the command and arguments to send
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly.
    
    Throws:
    
    NullPointerException - if request is null
  - send
```
public CompletableFuture<SmtpClientResponse> send(MessageContent content)
```
    Sends message content to the remote server and waits for a response.
    This method should be called when the server is in the "waiting for data" state, i.e. when the DATA command has been sent and the server has returned a 354 response.
    
    Parameters:
    
    content - the message contents to send
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly.
    
    Throws:
    
    NullPointerException - if content is null
    
    MessageTooLargeException - if the EHLO response indicated a maximum message size that would be exceeded by content. Note if MessageContent.size() is not specified this check is not performed.
  - sendChunk
```
public CompletableFuture<SmtpClientResponse> sendChunk(io.netty.buffer.ByteBuf data,
                                                       boolean isLast)
```
    Sends binary message content to the remote server and waits for a response.
    This method sends a BDAT command, immediately followed by the message contents, and depends on server support for SMTP chunking.
    
    Parameters:
    
    data - the message contents to send
    
    isLast - whether this is the last message chunk, and should included the LAST keyword with the BDAT command.
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly.
    
    Throws:
    
    NullPointerException - if data is null
    
    IllegalStateException - if the server does not support chunking, or if the EHLO response has not been received.
    
    MessageTooLargeException - if the EHLO response indicated a maximum message size that would be exceeded by content. Note if MessageContent.size() is not specified this check is not performed.
  - sendPipelined
```
public CompletableFuture<SmtpClientResponse> sendPipelined(io.netty.handler.codec.smtp.SmtpRequest... requests)
```
    Sends a series of commands to the server without waiting for a response.
    This is identical to sendPipelined(MessageContent, SmtpRequest...) but it does not send any message content.
  - sendPipelined
```
public CompletableFuture<SmtpClientResponse> sendPipelined(MessageContent content,
                                                           io.netty.handler.codec.smtp.SmtpRequest... requests)
```
    Sends a series of commands to the server without waiting for a response.
    This method reduces latency by sending all the specified commands without waiting for the server to respond to each one in turn. It depends on server support for SMTP pipelining.
    The server will send a response for each command included in the pipelined sequence. These are available from SmtpClientResponse.getResponses().
    According to the pipelining spec, the contents of one message can be sent together with a RSET and metadata for a subsequent message. As such, the content and requests arguments to this method refer to different e-mails.
    
    Parameters:
    
    content - the content to send
    
    requests - the commands to send
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the responses received from the remote server, or an exception if the send failed unexpectedly
    
    Throws:
    
    NullPointerException - if requests is null
    
    IllegalArgumentException - if the sequence of commands in requests is not valid according to the pipelining spec
    
    IllegalStateException - if the server does not support pipelining, or if the EHLO response has not been received
    
    MessageTooLargeException - if the EHLO response indicated a maximum message size that would be exceeded by content. Note if MessageContent.size() is not specified this check is not performed
  - authPlain
```
public CompletableFuture<SmtpClientResponse> authPlain(String username,
                                                       String password)
```
    Authenticates with the remote server using the PLAIN mechanism.
    
    Parameters:
    
    username - the plaintext username used to authenticate
    
    password - the plaintext password used to authenticate
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly
    
    Throws:
    
    IllegalStateException - if the server does not support PLAIN authentication, or if the EHLO response has not been received
  - authXoauth2
```
public CompletableFuture<SmtpClientResponse> authXoauth2(String username,
                                                         String accessToken)
```
    Authenticates with the remote server using the XOAUTH2 mechanism.
    
    Parameters:
    
    username - the plaintext username used to authenticate
    
    accessToken - the access token used to authenticate
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly
    
    Throws:
    
    IllegalStateException - if the server does not support XOAUTH2 authentication, or if the EHLO response has not been received
  - authLogin
```
public CompletableFuture<SmtpClientResponse> authLogin(String username,
                                                       String password)
```
    Authenticates with the remote server using the LOGIN mechanism.
    This method will attempt to send two commands to the server: the first includes the username, the second specifies the password. The returned SmtpClientResponse will contain the response to just one command - the first if the username was rejected by the server, or the second if the username was accepted and the password was sent.
    
    Parameters:
    
    username - the plaintext username used to authenticate
    
    password - the plaintext password used to authenticate
    
    Returns:
    
    a CompletableFuture<SmtpClientResponse> that will contain the response received from the remote server, or an exception if the send failed unexpectedly
    
    Throws:
    
    IllegalStateException - if the server does not support LOGIN authentication, or if the EHLO response has not been received

Class SmtpSession

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getConnectionId

getCloseFuture

getEhloResponse

close

startTls

isEncrypted

getSSLSession

send

send

send

send

send

send

sendChunk

sendPipelined

sendPipelined

authPlain

authXoauth2

authLogin